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

# API keys

> Create, inspect, and revoke environment-bound API keys.

API keys authenticate server-to-server requests. Every key belongs to one environment and combines permission scopes with optional tenant and knowledge-base allowlists.

<Note>
  All management endpoints on this page are **\[User]** only. Organization members may list and inspect keys; `owner` and `billing_admin` are required to create or revoke them.
</Note>

## Endpoints

| Method   | Path                        | Description                 | Auth          |
| -------- | --------------------------- | --------------------------- | ------------- |
| `POST`   | `/api-keys`                 | Create an API key           | \[User] admin |
| `GET`    | `/api-keys?environment_id=` | List keys in an environment | \[User]       |
| `GET`    | `/api-keys/:id`             | Get key metadata            | \[User]       |
| `DELETE` | `/api-keys/:id`             | Revoke a key                | \[User] admin |

## How access is resolved

| Access dimension     | Behavior                                                                                                                                       |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Environment          | A key is permanently bound to one environment and cannot reach resources in another environment.                                               |
| `tenant_ids`         | Optional tenant allowlist. An empty array grants access to every tenant in the environment; a non-empty array limits the key to those tenants. |
| `knowledge_base_ids` | Optional knowledge-base allowlist that narrows access within the allowed tenants. An empty array does not add a knowledge-base restriction.    |
| `scopes`             | Permission scopes such as `tenants:read`, `documents:write`, `skills:read`, or `query:rag`.                                                    |

<Warning>
  Resource allowlists and scopes solve different problems. A tenant ID in the allowlist does not grant a missing permission scope, and a permission scope does not let the key cross its environment boundary.
</Warning>

***

### Create an API key

`POST /api-keys`

<ParamField body="environment_id" type="string" required>
  Environment to bind the key to.
</ParamField>

<ParamField body="name" type="string">
  Human-readable key name.
</ParamField>

<ParamField body="scopes" type="string[]">
  Scopes to grant. If omitted or empty, the key receives the default tenant, knowledge-base, document, and RAG scopes described below.
</ParamField>

<ParamField body="tenant_ids" type="string[]">
  Tenant allowlist. Every ID must belong to `environment_id`. Omit or pass `[]` for all tenants in the environment.
</ParamField>

<ParamField body="knowledge_base_ids" type="string[]">
  Knowledge-base allowlist. Every ID must belong to the environment and, when `tenant_ids` is non-empty, to one of those tenants.
</ParamField>

<ParamField body="expires_in_days" type="number">
  Optional lifetime from 1 to 365 days. Keys without this field do not receive an API-configured expiration.
</ParamField>

```bash theme={null}
curl -X POST "https://api.autosage.ai/api/v1/api-keys" \
  -H "Cookie: YOUR_SESSION_COOKIE" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "ENVIRONMENT_ID",
    "name": "Production backend",
    "tenant_ids": ["TENANT_ID"],
    "knowledge_base_ids": [],
    "scopes": ["tenants:read", "knowledge_bases:read", "query:rag"],
    "expires_in_days": 90
  }'
```

The response contains metadata in `apiKey` and the complete secret in `rawKey`.

<Warning>
  `rawKey` is shown only once. Store it in a secret manager immediately; AutoSage cannot show the full value again. Never put an API key in browser code, mobile code, logs, or a public repository.
</Warning>

### Key prefixes

| Prefix     | Environment types          |
| ---------- | -------------------------- |
| `sk_live_` | `production`, `personal`   |
| `sk_test_` | `dev`, `staging`, `custom` |

If `scopes` is omitted or empty, the key receives:

```
tenants:read
tenants:write
knowledge_bases:read
knowledge_bases:write
documents:read
documents:write
query:rag
```

<Note>
  `admin:full` is a wildcard permission scope: it satisfies every API-key scope check, but it does not make a key eligible for user-session-only endpoints or let it cross its environment boundary. It also makes tenant discovery return every tenant in the environment, regardless of `tenant_ids`. Prefer explicit least-privilege scopes for production integrations.
</Note>

***

### List API keys

`GET /api-keys`

Returns key metadata, never complete secret values.

<ParamField query="environment_id" type="string" required>
  Environment whose keys to list.
</ParamField>

```bash theme={null}
curl "https://api.autosage.ai/api/v1/api-keys?environment_id=ENVIRONMENT_ID" \
  -H "Cookie: YOUR_SESSION_COOKIE"
```

Results include each key's ID, name, prefix, scopes, allowlists, status, expiration, last use, and creation metadata.

***

### Get an API key

`GET /api-keys/:id`

<ParamField path="id" type="string" required>
  API key ID, not the secret value.
</ParamField>

Returns metadata for one key. The response does not include `rawKey`.

***

### Revoke an API key

`DELETE /api-keys/:id`

<ParamField path="id" type="string" required>
  API key ID to revoke.
</ParamField>

```bash theme={null}
curl -X DELETE "https://api.autosage.ai/api/v1/api-keys/API_KEY_ID" \
  -H "Cookie: YOUR_SESSION_COOKIE"
```

Revocation disables the key immediately. Requests made with a revoked key are rejected, and a key that is already revoked cannot be revoked again.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/developers/authentication">
    Send keys safely and choose the right caller type.
  </Card>

  <Card title="Access & scopes" icon="shield" href="/developers/concepts/access-scopes">
    Build a least-privilege scope set.
  </Card>

  <Card title="Current caller" icon="user-shield" href="/developers/api/users">
    Inspect a key's effective environment and allowlists.
  </Card>
</CardGroup>