API Keys

Manage runtime API keys for projects

OpenAPIapi.spice.ai/openapi.json

Get API keys

GET/v1/projects/{projectId}/api-keys

Returns the API keys for a specific project. API keys are used to authenticate requests to the Spice.ai runtime.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/projects/<projectId>/api-keys" \
  -H "Authorization: Bearer <token>"

Responses

200OK
API keys for the project
application/json
- api_keystring | null
  Primary API key
- api_key_2string | null
  Secondary API key (for key rotation)
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or viewer role cannot regenerate API keys
404Not Found
Project not found
500Internal Server Error
Internal server error

Regenerate an API key

POST/v1/projects/{projectId}/api-keys

Regenerates an API key for the specified project. This invalidates the previous key. Use key_number to specify which key to regenerate (0 for both, 1 for primary, 2 for secondary).

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Optional

application/json

key_numberinteger
Which API key to regenerate (0 = both, 1 = primary, 2 = secondary)
- Allowed values: 0, 1, 2
- Default: 1

Example request

curl -X POST "https://api.spice.ai/v1/projects/<projectId>/api-keys" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "key_number": 1
  }'

Responses

200OK
API key regenerated successfully
application/json
- api_keystring | null
  Primary API key
- api_key_2string | null
  Secondary API key
- regenerated_keyinteger
  Which key was regenerated (0 = both, 1 = primary, 2 = secondary)
  - Allowed values: 0, 1, 2
400Bad Request
Invalid request body or project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
500Internal Server Error
Internal server error

Get API keys

GET/v1/orgs/{orgId}/projects/{projectId}/api-keys

The org is orgId in the path. Returns the API keys for a specific project. API keys are used to authenticate requests to the Spice.ai runtime.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/api-keys" \
  -H "Authorization: Bearer <token>"

Responses

200OK
API keys for the project
application/json
- api_keystring | null
  Primary API key
- api_key_2string | null
  Secondary API key (for key rotation)
400Bad Request
Invalid project ID. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or viewer role cannot regenerate API keys. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project not found
500Internal Server Error
Internal server error

Regenerate an API key

POST/v1/orgs/{orgId}/projects/{projectId}/api-keys

The org is orgId in the path. Regenerates an API key for the specified project. This invalidates the previous key. Use key_number to specify which key to regenerate (0 for both, 1 for primary, 2 for secondary).

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`projectId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	When present, X-Org-Name must name the same org as orgId. Otherwise the request returns org_path_mismatch (400). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Optional

application/json

key_numberinteger
Which API key to regenerate (0 = both, 1 = primary, 2 = secondary)
- Allowed values: 0, 1, 2
- Default: 1

Example request

curl -X POST "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/api-keys" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "key_number": 1
  }'

Responses

200OK
API key regenerated successfully
application/json
- api_keystring | null
  Primary API key
- api_key_2string | null
  Secondary API key
- regenerated_keyinteger
  Which key was regenerated (0 = both, 1 = primary, 2 = secondary)
  - Allowed values: 0, 1, 2
400Bad Request
Invalid request body or project ID. orgId is not a valid org id (invalid_org_id), or X-Org-Name does not name that org (org_path_mismatch).
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope. The caller is not a member of the org (org_forbidden). A machine credential named a different org (org_assertion_mismatch). The org is deleted (org_deleted).
404Not Found
Project not found
500Internal Server Error
Internal server error

Get API keys

GET/v1/apps/{appId}/api-keysDeprecated

Legacy alias of /v1/projects/{projectId}/api-keys — projects were previously called apps. Returns the API keys for a specific project. API keys are used to authenticate requests to the Spice.ai runtime.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Example request

curl "https://api.spice.ai/v1/apps/<appId>/api-keys" \
  -H "Authorization: Bearer <token>"

Responses

200OK
API keys for the project
application/json
- api_keystring | null
  Primary API key
- api_key_2string | null
  Secondary API key (for key rotation)
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or viewer role cannot regenerate API keys
404Not Found
Project not found
500Internal Server Error
Internal server error

Regenerate an API key

POST/v1/apps/{appId}/api-keysDeprecated

Legacy alias of /v1/projects/{projectId}/api-keys — projects were previously called apps. Regenerates an API key for the specified project. This invalidates the previous key. Use key_number to specify which key to regenerate (0 for both, 1 for primary, 2 for secondary).

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project

Header parameters

Name	Type	Required	Description
`Authorization`	string	Yes	`Bearer <token>`. Authentication lists the tokens it accepts.
`X-Org-Name`	string	No	The organization to act on, by handle. Omit it to act on the organization the credential is bound to; sending it blank is a 400, not the same as omitting it. A user credential may name any organization its owner belongs to; a machine credential is pinned to its own. A portal session token is bound to none, so it must send this header on every route but `GET /v1/orgs` (400 `org_assertion_required` otherwise). Pattern: `^[A-Za-z0-9._-]{1,255}$`

Request body

Optional

application/json

key_numberinteger
Which API key to regenerate (0 = both, 1 = primary, 2 = secondary)
- Allowed values: 0, 1, 2
- Default: 1

Example request

curl -X POST "https://api.spice.ai/v1/apps/<appId>/api-keys" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "key_number": 1
  }'

Responses

200OK
API key regenerated successfully
application/json
- api_keystring | null
  Primary API key
- api_key_2string | null
  Secondary API key
- regenerated_keyinteger
  Which key was regenerated (0 = both, 1 = primary, 2 = secondary)
  - Allowed values: 0, 1, 2
400Bad Request
Invalid request body or project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project not found
500Internal Server Error
Internal server error