> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebuly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

## Overview

Nebuly uses two distinct authentication mechanisms depending on the type of access.

**End-user authentication** is handled through your enterprise identity provider (Google,
Microsoft, Okta or built-in basic autnetication). Users log into the Nebuly UI via SSO or basic authentication.

**Ingestion authentication** uses API keys. Any service sending data (interactions, traces) to Nebuly must include a project API key in every request:

```http theme={null}
Authorization: Bearer <api-key>
```

API keys are scoped to a project and can be created under **Settings → Project → API keys**.

### Roles and permissions

Nebuly has four built-in roles. Assign them via the `role_mapping` in your SSO configuration
or manually through **Settings → Members**.

| Role           | Description                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------- |
| `admin`        | Full platform access. Manages members and all projects.                                      |
| `projectadmin` | Full access within a subset of projects. Can manage project members, API keys, and settings. |
| `member`       | Can view and interact with data within assigned projects. Cannot manage members or settings. |
| `viewer`       | Read-only access within assigned projects. Cannot modify any data or settings.               |

When using SSO, map each role to an IdP group in the `role_mapping` block. Users not
belonging to any mapped group will be denied access. At least one group must be mapped
to `admin` to ensure platform management is always accessible.

### Configuring SSO for self-hosted deployments

SSO is configured at the infrastructure level via the Nebuly Terraform module.
Pass your identity provider credentials as a module input and Terraform will
automatically inject them into the generated Helm values.

Supported providers: `google`, `microsoft`, `okta`.

```hcl theme={null}
module "platform" {
  source = "nebuly-ai/nebuly-platform/azurerm" # or /aws, /google

  google_sso = {
    client_id     = "<your-client-id>"
    client_secret = "<your-client-secret>"
    role_mapping = {
      "viewer"       = "<idp-group>"
      "member"       = "<idp-group>"
      "admin"        = "<idp-group>"
      "projectadmin" = "<idp-group>"
    }
  }
}
```

The `role_mapping` field maps IdP groups to Nebuly roles. Ensure the groups exist in your
identity provider before applying. After `terraform apply`, re-run `terraform output helm_values`
to pick up the updated values before upgrading the Helm chart.

Terraform module references:
[AWS](https://registry.terraform.io/modules/nebuly-ai/nebuly-platform/aws/latest) ·
[Azure](https://registry.terraform.io/modules/nebuly-ai/nebuly-platform/azurerm/latest) ·
[GCP](https://registry.terraform.io/modules/nebuly-ai/nebuly-platform/google/latest)