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

# Authentication

> API keys, scopes, signup, and login for the MeshAI API

## API Keys

MeshAI uses Bearer token authentication. All API keys start with `msh_`.

```bash theme={null}
curl https://api.meshai.dev/api/v1/agents \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

### Key Types

| Type          | Prefix | Permissions                                                  |
| ------------- | ------ | ------------------------------------------------------------ |
| **Admin**     | `msh_` | Full access: manage agents, policies, billing, users         |
| **Proxy**     | `msh_` | Forward LLM requests through the proxy; read-only agent data |
| **Read-only** | `msh_` | Read agents, cost, anomalies; no write operations            |

### Scopes

API keys are scoped to limit permissions:

| Scope              | Allows                                              |
| ------------------ | --------------------------------------------------- |
| `registry:read`    | List and get agents, teams                          |
| `registry:write`   | Register, update, delete agents and teams           |
| `telemetry:write`  | Send heartbeats and usage data                      |
| `monitoring:read`  | Query monitoring overview                           |
| `cost:read`        | Query cost endpoints                                |
| `anomaly:read`     | List and get anomalies                              |
| `anomaly:write`    | Acknowledge, resolve anomalies                      |
| `governance:read`  | List policies, approvals, audit events              |
| `governance:write` | Create policies, decide approvals, classify risk    |
| `proxy:forward`    | Forward LLM requests through the proxy              |
| `admin`            | Full access: manage keys, agents, policies, billing |
| `platform:admin`   | Tenant management (platform admins only)            |

### Scope Restrictions

When creating a new API key, the scopes you can grant depend on your own key's permissions:

| Your scope       | Can grant                          |
| ---------------- | ---------------------------------- |
| `platform:admin` | Any scope                          |
| `admin`          | All scopes except `platform:admin` |
| Other            | Only scopes you already have       |

Attempting to grant a scope you don't have returns `403 Forbidden`.

## Get Current Key Info

```
GET /auth/me
```

Returns the scopes and identity of the API key making the request. Useful for determining which scopes are available when creating new keys.

```bash theme={null}
curl https://api.meshai.dev/api/v1/auth/me \
  -H "Authorization: Bearer msh_YOUR_API_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "key_id": "01JABC123DEF456",
      "tenant_id": "01JXYZ789GHI012",
      "scopes": ["admin"]
    }
  }
  ```
</ResponseExample>

## Create an API Key

### Via Dashboard

Go to [app.meshai.dev/settings/api-keys](https://app.meshai.dev/settings/api-keys) and click "Create API Key". Select the scopes you need.

### Via API

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/auth/api-keys \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline-key",
    "scopes": ["registry:read", "registry:write", "telemetry:write"],
    "expires_in_days": 90
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "01JABC123DEF456",
      "raw_key": "msh_abc123def456...",
      "key_prefix": "msh_abc1",
      "name": "ci-pipeline-key",
      "scopes": ["registry:read", "registry:write", "telemetry:write"],
      "expires_at": "2026-06-15T10:00:00Z",
      "created_at": "2026-03-17T10:00:00Z"
    }
  }
  ```
</ResponseExample>

<Warning>
  The API key is shown once at creation time. Store it securely. You cannot retrieve it later.
</Warning>

## Signup

Create a new MeshAI account:

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com",
    "password": "secure-password",
    "company_name": "Acme Corp"
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "tenant_id": "tnt_abc123",
      "user_id": "usr_def456",
      "api_key": "msh_live_abc123def456",
      "message": "Account created. Check your email to verify."
    }
  }
  ```
</ResponseExample>

## Login

Get a session token for dashboard access or exchange for an API key:

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com",
    "password": "secure-password"
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "access_token": "eyJhbGciOi...",
      "token_type": "bearer",
      "expires_in": 3600,
      "tenant_id": "tnt_abc123"
    }
  }
  ```
</ResponseExample>

## Key Rotation

Rotate keys without downtime by creating a new key before deleting the old one:

<Steps>
  <Step title="Create a new key">
    Create a new API key with the same scopes.
  </Step>

  <Step title="Update your agents">
    Deploy the new key to all agents and services.
  </Step>

  <Step title="Delete the old key">
    Once all agents are using the new key, delete the old one:

    ```bash theme={null}
    curl -X DELETE https://api.meshai.dev/api/v1/auth/api-keys/key_old123 \
      -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"
    ```
  </Step>
</Steps>

## SAML SSO

SAML-based single sign-on for your organization's identity provider. Available on the Enterprise plan (and Enterprise Plus, and internal partner tenants). All SSO endpoints require the `admin` scope.

### Get SSO Configuration

```
GET /sso/config
```

Get the tenant's current SSO configuration, or `null` if SSO has not been configured yet.

```bash theme={null}
curl https://api.meshai.dev/api/v1/sso/config \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "01JSSO1CONFIG2ABC3DEF456",
      "provider_name": "Okta",
      "idp_entity_id": "http://www.okta.com/exkabc123",
      "idp_sso_url": "https://acme.okta.com/app/acme_meshai/exkabc123/sso/saml",
      "idp_slo_url": null,
      "enabled": true,
      "auto_provision": true,
      "created_at": "2026-03-01T00:00:00Z"
    }
  }
  ```
</ResponseExample>

### Configure SSO

```
POST /sso/config
```

Create or update the tenant's SAML SSO configuration. Returns `403` if the tenant's plan does not include SSO.

| Field            | Type    | Required | Description                                           |
| ---------------- | ------- | -------- | ----------------------------------------------------- |
| `provider_name`  | string  | Yes      | Display name for the identity provider (e.g., `Okta`) |
| `idp_entity_id`  | string  | Yes      | IdP entity ID                                         |
| `idp_sso_url`    | string  | Yes      | IdP SSO URL                                           |
| `idp_slo_url`    | string  | No       | IdP single logout URL                                 |
| `idp_x509_cert`  | string  | Yes      | IdP signing certificate                               |
| `auto_provision` | boolean | No       | Auto-create users on first SSO login (default `true`) |

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/sso/config \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_name": "Okta",
    "idp_entity_id": "http://www.okta.com/exkabc123",
    "idp_sso_url": "https://acme.okta.com/app/acme_meshai/exkabc123/sso/saml",
    "idp_x509_cert": "-----BEGIN CERTIFICATE-----..."
  }'
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "01JSSO1CONFIG2ABC3DEF456",
      "created": true
    }
  }
  ```
</ResponseExample>

### Enable SSO

```
POST /sso/enable
```

Enable SSO for the tenant. Requires an existing SSO configuration; returns `400` if none exists yet.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/sso/enable \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"
```

### Disable SSO

```
POST /sso/disable
```

Disable SSO for the tenant without deleting its configuration.

```bash theme={null}
curl -X POST https://api.meshai.dev/api/v1/sso/disable \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"
```

### Get SP Metadata

```
GET /sso/metadata
```

Get the MeshAI service provider metadata your identity provider needs to complete the SAML integration.

```bash theme={null}
curl https://api.meshai.dev/api/v1/sso/metadata \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"
```

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "entity_id": "https://app.meshai.dev/sso",
      "acs_url": "https://app.meshai.dev/api/auth/sso/callback",
      "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
    }
  }
  ```
</ResponseExample>