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.

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.

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`.

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.

Create an API key

POST /api-keys

string

required

Environment to bind the key to.

string

Human-readable key name.

string[]

Scopes to grant. If omitted or empty, the key receives the default tenant, knowledge-base, document, and RAG scopes described below.

string[]

Tenant allowlist. Every ID must belong to environment_id. Omit or pass [] for all tenants in the environment.

string[]

Knowledge-base allowlist. Every ID must belong to the environment and, when tenant_ids is non-empty, to one of those tenants.

number

Optional lifetime from 1 to 365 days. Keys without this field do not receive an API-configured expiration.

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.

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.

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

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.

List API keys

GET /api-keys Returns key metadata, never complete secret values.

string

required

Environment whose keys to list.

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

string

required

API key ID, not the secret value.

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

Revoke an API key

DELETE /api-keys/:id

string

required

API key ID to revoke.

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

Authentication

Send keys safely and choose the right caller type.

Access & scopes

Build a least-privilege scope set.

Current caller

Inspect a key’s effective environment and allowlists.

Get started

Core concepts

Lifecycles

Guides

API reference

Endpoints

How access is resolved

Create an API key

Key prefixes

List API keys

Get an API key

Revoke an API key

Next steps

Authentication

Access & scopes

Current caller

​Endpoints

​How access is resolved

​Create an API key

​Key prefixes

​List API keys

​Get an API key

​Revoke an API key

​Next steps

Authentication

Access & scopes

Current caller

Endpoints

How access is resolved

Create an API key

Key prefixes

List API keys

Get an API key

Revoke an API key

Next steps