Authentication & API Keys
Authenticate to the Platform API with workspace keys or device authorization, inspect the live permission catalog, and rotate or revoke credentials safely.
API Key Usage
curl https://api.platform.amigo.ai/v1/{workspace_id}/agents \
-H "Authorization: Bearer <YOUR_API_KEY>"API Key Lifecycle
Create an API Key
Create a new API key for a workspace. The response includes the plaintext api_key — store it securely, it cannot be retrieved again.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
memberPermission names. Max 128 entries; each entry up to 128 chars.
Successful Response
Missing or invalid API key.
Insufficient permissions or requested role exceeds caller access.
Invalid request body or role.
Canonical API key role configuration unavailable.
POST /v1/{workspace_id}/api-keys HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 72
{
"name": "text",
"duration_days": 1,
"role": "member",
"permissions": [
"text"
]
}{
"key_id": "text",
"api_key": "text",
"name": "text",
"role": "text",
"permissions": [
"text"
],
"expires_at": "2026-01-01T00:00:00.000Z",
"created_by_entity_id": "123e4567-e89b-12d3-a456-426614174000",
"created_by_credential_id": "123e4567-e89b-12d3-a456-426614174000"
}List API Keys
List all API keys for a workspace with pagination. Requires ApiKey.view permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
[]50falseSuccessful Response
Missing or invalid API key.
Insufficient permissions.
Validation Error
Canonical API key role configuration unavailable.
GET /v1/{workspace_id}/api-keys HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"items": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"created_by_entity_id": "123e4567-e89b-12d3-a456-426614174000",
"created_by_credential_id": "123e4567-e89b-12d3-a456-426614174000",
"key_id": "text",
"name": "text",
"role": "text",
"permissions": [
"text"
],
"expires_at": "2026-01-01T00:00:00.000Z",
"last_used_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"has_more": true,
"continuation_token": null
}Revoke an API Key
Revoke an API key. Requires ApiKey.delete permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
No content
Missing or invalid API key.
Insufficient permissions.
API key not found.
Validation Error
DELETE /v1/{workspace_id}/api-keys/{key_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
RBAC Roles
Permission Catalog
Return the authoritative role→permission model: each role's default permission set (what an API key of that role may carry) plus the full permission universe. Clients use this to build the create-key form instead of hard-coding the matrix. Requires ApiKey.view permission.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
The authoritative role→permission model for API-key creation.
Serves the server-side source of truth (DEFAULT_ROLE_DEFINITIONS) so
clients (console, SDK) stop hand-copying the matrix and drifting out of
sync — a drift previously shipped Data:Query as a viewer default and
made the default create flow 422. Human-facing labels/descriptions for
individual permissions stay client-side (pure presentation); this payload
is authorization truth only.
Missing or invalid API key.
Insufficient permissions.
GET /v1/{workspace_id}/api-keys/permission-catalog HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"roles": [
{
"name": "text",
"priority": 1,
"description": "text",
"permission_names": [
"text"
]
}
],
"permissions": [
{
"name": "text",
"namespace": "text",
"action": "text"
}
]
}Key Rotation
Replace an API key secret in one step. The old secret stops working immediately, and the response includes the new plaintext api_key exactly once.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Missing or invalid API key.
Insufficient permissions.
API key not found.
Validation Error
POST /v1/{workspace_id}/api-keys/{key_id}/rotate HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 19
{
"duration_days": 1
}{
"key_id": "text",
"api_key": "text",
"name": "text",
"role": "text",
"permissions": [
"text"
],
"expires_at": "2026-01-01T00:00:00.000Z",
"created_by_entity_id": "123e4567-e89b-12d3-a456-426614174000",
"created_by_credential_id": "123e4567-e89b-12d3-a456-426614174000"
}Usage Visibility
Current Key Info
Return information about the currently authenticated API key, including expiration.
API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.
Successful Response
Missing or invalid API key.
GET /v1/auth/me HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workspace_id": "123e4567-e89b-12d3-a456-426614174000",
"key_id": "text",
"name": "text",
"expires_at": "2026-01-01T00:00:00.000Z",
"expires_in_seconds": 1
}Device Code Flow (CLI & Desktop Apps)
Flow Overview
Step-by-Step
Multi-Workspace Users
Platform SDK (TypeScript)
Security
Security Controls
SSO Login
SSO Exchange Flow
Multi-Workspace Selection
Auto-Provisioning
Refresh Tokens
Multi-Factor Authentication (MFA)
Enrollment Flow
MFA Enforcement
Recovery Codes
Admin MFA Management
IP Allowlists
Allowlist Behavior
Admin IP Allowlist Management
Account Lockout & Brute Force Protection
Session Enforcement
Idle Timeout
Concurrent Session Limits
Session Metadata
Session Management Endpoints
Last updated
Was this helpful?