Skip to main content
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

MethodPathDescriptionAuth
POST/api-keysCreate an API key[User] admin
GET/api-keys?environment_id=List keys in an environment[User]
GET/api-keys/:idGet key metadata[User]
DELETE/api-keys/:idRevoke a key[User] admin

​
How access is resolved

Access dimensionBehavior
EnvironmentA key is permanently bound to one environment and cannot reach resources in another environment.
tenant_idsOptional 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_idsOptional knowledge-base allowlist that narrows access within the allowed tenants. An empty array does not add a knowledge-base restriction.
scopesPermission 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
​
environment_id
string
required
Environment to bind the key to.
​
name
string
Human-readable key name.
​
scopes
string[]
Scopes to grant. If omitted or empty, the key receives the default tenant, knowledge-base, document, and RAG scopes described below.
​
tenant_ids
string[]
Tenant allowlist. Every ID must belong to environment_id. Omit or pass [] for all tenants in the environment.
​
knowledge_base_ids
string[]
Knowledge-base allowlist. Every ID must belong to the environment and, when tenant_ids is non-empty, to one of those tenants.
​
expires_in_days
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

PrefixEnvironment 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.
​
environment_id
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
​
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
​
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.