# API Keys

Manage API keys

## GET /api-keys

> List API keys

```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"API Keys","description":"Manage API keys"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"schemas":{"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string","description":"First 12 characters of the key"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyScope"}},"allowed_ips":{"type":"array","items":{"type":"string"}},"requests_24h":{"type":"integer"},"requests_30d":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","nullable":true},"last_used_at":{"type":"string","format":"date-time","nullable":true},"revoked_at":{"type":"string","format":"date-time","nullable":true},"organization_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"}}},"ApiKeyScope":{"type":"string","enum":["calls:read","calls:write","numbers:read","numbers:write","endpoints:read","endpoints:write","webhooks:read","webhooks:write","analytics:read","billing:read","billing:write"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}},"responses":{"Unauthorized":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api-keys":{"get":{"tags":["API Keys"],"summary":"List API keys","operationId":"listApiKeys","parameters":[{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"List of API keys (keys are masked)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## Create API key

> Creates a new API key. The full key is only returned once\
> in this response and cannot be retrieved again.<br>

```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"API Keys","description":"Manage API keys"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"schemas":{"ApiKeyCreate":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyScope"}},"allowed_ips":{"type":"array","items":{"type":"string"},"description":"IP addresses or CIDR ranges allowed to use this key"},"expires_at":{"type":"string","format":"date-time","nullable":true}}},"ApiKeyScope":{"type":"string","enum":["calls:read","calls:write","numbers:read","numbers:write","endpoints:read","endpoints:write","webhooks:read","webhooks:write","analytics:read","billing:read","billing:write"]},"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string","description":"First 12 characters of the key"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyScope"}},"allowed_ips":{"type":"array","items":{"type":"string"}},"requests_24h":{"type":"integer"},"requests_30d":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","nullable":true},"last_used_at":{"type":"string","format":"date-time","nullable":true},"revoked_at":{"type":"string","format":"date-time","nullable":true},"organization_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}},"responses":{"BadRequest":{"description":"Bad request - Invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api-keys":{"post":{"tags":["API Keys"],"summary":"Create API key","description":"Creates a new API key. The full key is only returned once\nin this response and cannot be retrieved again.\n","operationId":"createApiKey","parameters":[{"$ref":"#/components/parameters/OrganizationId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreate"}}}},"responses":{"201":{"description":"API key created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"full_key":{"type":"string","description":"The full API key (only shown once)"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```

## GET /api-keys/{id}

> Get API key details

```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"API Keys","description":"Manage API keys"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"ApiKeyId":{"name":"id","in":"path","required":true,"description":"API key UUID","schema":{"type":"string","format":"uuid"}},"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"schemas":{"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string","description":"First 12 characters of the key"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyScope"}},"allowed_ips":{"type":"array","items":{"type":"string"}},"requests_24h":{"type":"integer"},"requests_30d":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","nullable":true},"last_used_at":{"type":"string","format":"date-time","nullable":true},"revoked_at":{"type":"string","format":"date-time","nullable":true},"organization_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"}}},"ApiKeyScope":{"type":"string","enum":["calls:read","calls:write","numbers:read","numbers:write","endpoints:read","endpoints:write","webhooks:read","webhooks:write","analytics:read","billing:read","billing:write"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api-keys/{id}":{"get":{"tags":["API Keys"],"summary":"Get API key details","operationId":"getApiKey","parameters":[{"$ref":"#/components/parameters/ApiKeyId"},{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"API key details (key is masked)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## DELETE /api-keys/{id}

> Revoke API key

```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"API Keys","description":"Manage API keys"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"ApiKeyId":{"name":"id","in":"path","required":true,"description":"API key UUID","schema":{"type":"string","format":"uuid"}},"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}}},"paths":{"/api-keys/{id}":{"delete":{"tags":["API Keys"],"summary":"Revoke API key","operationId":"revokeApiKey","parameters":[{"$ref":"#/components/parameters/ApiKeyId"},{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"204":{"description":"API key revoked"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## PATCH /api-keys/{id}

> Update API key

```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"API Keys","description":"Manage API keys"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"ApiKeyId":{"name":"id","in":"path","required":true,"description":"API key UUID","schema":{"type":"string","format":"uuid"}},"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"schemas":{"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string","description":"First 12 characters of the key"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyScope"}},"allowed_ips":{"type":"array","items":{"type":"string"}},"requests_24h":{"type":"integer"},"requests_30d":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","nullable":true},"last_used_at":{"type":"string","format":"date-time","nullable":true},"revoked_at":{"type":"string","format":"date-time","nullable":true},"organization_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"}}},"ApiKeyScope":{"type":"string","enum":["calls:read","calls:write","numbers:read","numbers:write","endpoints:read","endpoints:write","webhooks:read","webhooks:write","analytics:read","billing:read","billing:write"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}},"responses":{"BadRequest":{"description":"Bad request - Invalid parameters or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api-keys/{id}":{"patch":{"tags":["API Keys"],"summary":"Update API key","operationId":"updateApiKey","parameters":[{"$ref":"#/components/parameters/ApiKeyId"},{"$ref":"#/components/parameters/OrganizationId"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":100},"scopes":{"type":"array","items":{"type":"string"}},"allowed_ips":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string","format":"date-time","nullable":true},"status":{"type":"string","enum":["active","revoked"]}}}}}},"responses":{"200":{"description":"API key updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKey"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Regenerate API key

> Regenerates the API key, invalidating the old one.\
> The new full key is only returned once.<br>

```json
{"openapi":"3.0.3","info":{"title":"KrosAI Cockpit API","version":"1.3.0"},"tags":[{"name":"API Keys","description":"Manage API keys"}],"servers":[{"url":"https://api.krosai.com/v1","description":"Production API"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key in format `kros_live_xxxx` for production or `kros_test_xxxx` for testing.\nAlso accepts JWT tokens from Supabase Auth for dashboard sessions.\n\n**Alternative:** You can also use the `x-api-key` header instead of Authorization Bearer.\n"}},"parameters":{"ApiKeyId":{"name":"id","in":"path","required":true,"description":"API key UUID","schema":{"type":"string","format":"uuid"}},"OrganizationId":{"name":"x-organization-id","in":"header","required":false,"description":"Organization UUID for multi-tenant context. Falls back to user's first organization if not provided.","schema":{"type":"string","format":"uuid"}}},"schemas":{"ApiKey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"key_prefix":{"type":"string","description":"First 12 characters of the key"},"scopes":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyScope"}},"allowed_ips":{"type":"array","items":{"type":"string"}},"requests_24h":{"type":"integer"},"requests_30d":{"type":"integer"},"expires_at":{"type":"string","format":"date-time","nullable":true},"last_used_at":{"type":"string","format":"date-time","nullable":true},"revoked_at":{"type":"string","format":"date-time","nullable":true},"organization_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"}}},"ApiKeyScope":{"type":"string","enum":["calls:read","calls:write","numbers:read","numbers:write","endpoints:read","endpoints:write","webhooks:read","webhooks:write","analytics:read","billing:read","billing:write"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"},"details":{"type":"object","additionalProperties":true,"description":"Additional error details"}}}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api-keys/{id}/regenerate":{"post":{"tags":["API Keys"],"summary":"Regenerate API key","description":"Regenerates the API key, invalidating the old one.\nThe new full key is only returned once.\n","operationId":"regenerateApiKey","parameters":[{"$ref":"#/components/parameters/ApiKeyId"},{"$ref":"#/components/parameters/OrganizationId"}],"responses":{"200":{"description":"API key regenerated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ApiKey"},{"type":"object","properties":{"full_key":{"type":"string","description":"The new full API key (only shown once)"}}}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.krosai.com/api-reference/reference/api-keys.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.