# API Keys

## List API keys

> List all API keys for a workspace with pagination. Requires \`ApiKey.view\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"PaginatedResponse_ApiKeyResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/ApiKeyResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[ApiKeyResponse]"},"ApiKeyResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"created_by_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Entity Id"},"created_by_credential_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Credential Id"},"key_id":{"type":"string","title":"Key Id"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"role":{"type":"string","title":"Role"},"permissions":{"items":{"type":"string"},"type":"array","title":"Permissions"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"}},"type":"object","required":["id","workspace_id","created_by_entity_id","created_by_credential_id","key_id","name","role","permissions","expires_at","last_used_at","created_at","updated_at"],"title":"ApiKeyResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/api-keys":{"get":{"tags":["API Keys"],"summary":"List API keys","description":"List all API keys for a workspace with pagination. Requires `ApiKey.view` permission.","operationId":"list-api-keys","parameters":[{"name":"mine_only","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Mine Only"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":20,"exclusiveMinimum":0,"default":10,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_ApiKeyResponse_"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"CreateApiKeyRequest":{"properties":{"name":{"anyOf":[{"$ref":"#/components/schemas/StrippedNonemptyString"},{"type":"null"}]},"duration_days":{"type":"integer","maximum":90,"minimum":1,"title":"Duration Days"},"role":{"type":"string","title":"Role","default":"member"},"permissions":{"items":{"type":"string"},"type":"array","title":"Permissions"}},"type":"object","required":["duration_days"],"title":"CreateApiKeyRequest"},"StrippedNonemptyString":{"type":"string","minLength":1},"CreateApiKeyResponse":{"properties":{"key_id":{"type":"string","title":"Key Id"},"api_key":{"type":"string","title":"Api Key"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"role":{"type":"string","title":"Role"},"permissions":{"items":{"type":"string"},"type":"array","title":"Permissions"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"created_by_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Entity Id"},"created_by_credential_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Credential Id"}},"type":"object","required":["key_id","api_key","name","role","permissions","expires_at","created_by_entity_id","created_by_credential_id"],"title":"CreateApiKeyResponse"}}},"paths":{"/v1/{workspace_id}/api-keys":{"post":{"tags":["API Keys"],"summary":"Create an API key","description":"Create a new API key for a workspace. The response includes the plaintext `api_key` — store it securely, it cannot be retrieved again.","operationId":"create-api-key","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions or requested role exceeds caller access."},"422":{"description":"Invalid request body or role."}}}}}}
```

## Delete an API key

> Revoke an API key. Requires \`ApiKey.delete\` permission.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/api-keys/{key_id}":{"delete":{"tags":["API Keys"],"summary":"Delete an API key","description":"Revoke an API key. Requires `ApiKey.delete` permission.","operationId":"delete-api-key","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"API key not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Rotate an API key

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"RotateApiKeyRequest":{"properties":{"duration_days":{"type":"integer","maximum":90,"minimum":1,"title":"Duration Days"}},"type":"object","required":["duration_days"],"title":"RotateApiKeyRequest"},"CreateApiKeyResponse":{"properties":{"key_id":{"type":"string","title":"Key Id"},"api_key":{"type":"string","title":"Api Key"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name"},"role":{"type":"string","title":"Role"},"permissions":{"items":{"type":"string"},"type":"array","title":"Permissions"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"created_by_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Entity Id"},"created_by_credential_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created By Credential Id"}},"type":"object","required":["key_id","api_key","name","role","permissions","expires_at","created_by_entity_id","created_by_credential_id"],"title":"CreateApiKeyResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/api-keys/{key_id}/rotate":{"post":{"tags":["API Keys"],"summary":"Rotate an API key","description":"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.","operationId":"rotate-api-key","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string","title":"Key Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateApiKeyRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyResponse"}}}},"401":{"description":"Missing or invalid API key."},"403":{"description":"Insufficient permissions."},"404":{"description":"API key not found."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```