Secrets

Manage encrypted project secrets

OpenAPIapi.spice.ai/openapi.json

List secrets

GET/v1/projects/{projectId}/secrets

Returns all secrets for the specified project. Secret values are always masked.

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>/secrets" \
  -H "Authorization: Bearer <token>"

Responses

200OK
List of secrets
application/json
- secretsarray of object
  5 properties
  idinteger
  Unique identifier for the secret
  namestring
  Name of the secret
  valuestring
  Always masked with asterisks
  created_atstring (date-time)
  Timestamp when the secret was created
  updated_atstring (date-time)
  Timestamp when the secret was last updated
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or viewer role cannot perform write operations
404Not Found
Project not found
500Internal Server Error
Internal server error

Create or update a secret

POST/v1/projects/{projectId}/secrets

Creates a new secret or updates an existing secret with the same name. The secret value is encrypted at rest.

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

Required

application/json

namestringRequired
Secret name (must start with a letter or underscore, alphanumeric and underscores only)
- Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
valuestringRequired
Secret value (will be encrypted at rest)

Example request

curl -X POST "https://api.spice.ai/v1/projects/<projectId>/secrets" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "value": "string"
  }'

Responses

200OK
Secret created or updated successfully
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
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 a secret

GET/v1/projects/{projectId}/secrets/{secretName}

Returns a specific secret by name. The secret value is always masked.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project
`secretName`	string	Yes	The name of the secret

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>/secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Secret details (value is masked)
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or admin or owner role required
404Not Found
Project or secret not found
500Internal Server Error
Internal server error

Delete a secret

DELETE/v1/projects/{projectId}/secrets/{secretName}

Permanently deletes a secret by name.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project
`secretName`	string	Yes	The name of the secret

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 -X DELETE "https://api.spice.ai/v1/projects/<projectId>/secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

204No Content
Secret deleted successfully
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project or secret not found
500Internal Server Error
Internal server error

List the organization secrets linked to a project

GET/v1/projects/{projectId}/org-secrets

Returns the organization secrets this project receives at deploy time. Values are always masked. shadowed is true when a project secret has the same name; the project secret is the one delivered.

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>/org-secrets" \
  -H "Authorization: Bearer <token>"

Responses

200OK
The linked organization secrets, masked
application/json
- org_secretsarray of object
  6 properties
  idinteger
  Unique identifier for the secret
  namestring
  Name of the secret
  valuestring
  Always masked with asterisks
  created_atstring (date-time)
  Timestamp when the secret was created
  updated_atstring (date-time)
  Timestamp when the secret was last updated
  shadowedboolean
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (requires secrets:read) or the viewer role
404Not Found
Project not found
500Internal Server Error
Internal server error

Link an organization secret to a project

PUT/v1/projects/{projectId}/org-secrets/{secretName}

Makes the named organization secret available to the project at deploy time. Linking a secret that is already linked changes nothing. The project's own secrets are not changed; a project secret with the same name takes precedence.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project
`secretName`	string	Yes	The name of the organization secret

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 -X PUT "https://api.spice.ai/v1/projects/<projectId>/org-secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
The secret was already linked
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
201Created
The secret was linked
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
400Bad Request
Invalid project ID or secret name
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (requires secrets:write) or the viewer role
404Not Found
Project or organization secret not found
409Conflict
The project already links the maximum of 1000 organization secrets (code: org_secret_link_limit)
429Too Many Requests
Another link change is in progress for this project. Try again.
500Internal Server Error
Internal server error
503Service Unavailable
Failed to link the organization secret. Try again.

Unlink an organization secret from a project

DELETE/v1/projects/{projectId}/org-secrets/{secretName}

Stops delivering the named organization secret to the project from its next deploy. The secret itself is kept.

Path parameters

Name	Type	Required	Description
`projectId`	integer	Yes	The ID of the project
`secretName`	string	Yes	The name of the organization secret

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 -X DELETE "https://api.spice.ai/v1/projects/<projectId>/org-secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

204No Content
The secret was unlinked
400Bad Request
Invalid project ID or secret name
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (requires secrets:write) or the viewer role
404Not Found
Project or organization secret not found, or the secret is not linked to the project
429Too Many Requests
Another link change is in progress for this project. Try again.
500Internal Server Error
Internal server error
503Service Unavailable
Failed to unlink the organization secret. Try again.

List organization secrets

GET/v1/orgs/{orgId}/secrets

Returns the organization's secrets. Values are always masked. Platform-managed secrets are not listed. An organization secret reaches a project only through a link (see /v1/projects/{projectId}/org-secrets).

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`

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>/secrets" \
  -H "Authorization: Bearer <token>"

Responses

200OK
The organization's secrets, masked
application/json
- secretsarray of object
  5 properties
  idinteger
  Unique identifier for the secret
  namestring
  Name of the secret
  valuestring
  Always masked with asterisks
  created_atstring (date-time)
  Timestamp when the secret was created
  updated_atstring (date-time)
  Timestamp when the secret was last updated
400Bad Request
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 (requires secrets:read), the viewer role, or the caller is not a member of the organization (org_forbidden), a machine credential named an organization other than its own (org_assertion_mismatch), or the organization a machine credential is bound to has been deleted (org_deleted)
500Internal Server Error
Internal server error

Create or update an organization secret

POST/v1/orgs/{orgId}/secrets

Creates an organization secret, or replaces the value of the one with the same name. The value is encrypted at rest and never returned. A name reserved by a platform-managed secret is refused.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`

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

Required

application/json

namestringRequired
- Maximum length: 255
- Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
valuestringRequired
- Maximum length: 10000

Example request

curl -X POST "https://api.spice.ai/v1/orgs/<orgId>/secrets" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "value": "string"
  }'

Responses

200OK
The existing secret's value was replaced
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
201Created
The secret was created
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
400Bad Request
Invalid org id (invalid_org_id), X-Org-Name does not name that org (org_path_mismatch), or the JSON body is not valid
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (requires secrets:write), the viewer role, or the caller is not a member of the organization (org_forbidden), a machine credential named an organization other than its own (org_assertion_mismatch), or the organization a machine credential is bound to has been deleted (org_deleted)
409Conflict
The name is reserved by a platform-managed secret (code: secret_name_reserved)
413Content Too Large
Request body too large
500Internal Server Error
Internal server error

Get an organization secret

GET/v1/orgs/{orgId}/secrets/{secretName}

Returns one organization secret's metadata. The value is always masked.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`secretName`	string	Yes	The name of the secret

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>/secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
The secret, masked
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
400Bad Request
Invalid org id (invalid_org_id), X-Org-Name does not name that org (org_path_mismatch), or invalid secret name
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (requires secrets:read), the viewer role, or the caller is not a member of the organization (org_forbidden), a machine credential named an organization other than its own (org_assertion_mismatch), or the organization a machine credential is bound to has been deleted (org_deleted)
404Not Found
Secret not found
500Internal Server Error
Internal server error

Delete an organization secret

DELETE/v1/orgs/{orgId}/secrets/{secretName}

Deletes an organization secret and every project link to it. Deployments that reference it stop receiving it on their next deploy.

Path parameters

Name	Type	Required	Description
`orgId`	integer	Yes	The org id from GET /v1/orgs Minimum: `1`
`secretName`	string	Yes	The name of the secret

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 -X DELETE "https://api.spice.ai/v1/orgs/<orgId>/secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

204No Content
Secret deleted
400Bad Request
Invalid org id (invalid_org_id), X-Org-Name does not name that org (org_path_mismatch), or invalid secret name
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (requires secrets:write), the caller is not an admin or owner, or not a member of the organization (org_forbidden), a machine credential named an organization other than its own (org_assertion_mismatch), or the organization a machine credential is bound to has been deleted (org_deleted)
404Not Found
Secret not found
500Internal Server Error
Internal server error

List secrets

GET/v1/orgs/{orgId}/projects/{projectId}/secrets

The org is orgId in the path. Returns all secrets for the specified project. Secret values are always masked.

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>/secrets" \
  -H "Authorization: Bearer <token>"

Responses

200OK
List of secrets
application/json
- secretsarray of object
  5 properties
  idinteger
  Unique identifier for the secret
  namestring
  Name of the secret
  valuestring
  Always masked with asterisks
  created_atstring (date-time)
  Timestamp when the secret was created
  updated_atstring (date-time)
  Timestamp when the secret was last updated
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 perform write operations. 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

Create or update a secret

POST/v1/orgs/{orgId}/projects/{projectId}/secrets

The org is orgId in the path. Creates a new secret or updates an existing secret with the same name. The secret value is encrypted at rest.

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

Required

application/json

namestringRequired
Secret name (must start with a letter or underscore, alphanumeric and underscores only)
- Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
valuestringRequired
Secret value (will be encrypted at rest)

Example request

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

Responses

200OK
Secret created or updated successfully
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
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 a secret

GET/v1/orgs/{orgId}/projects/{projectId}/secrets/{secretName}

The org is orgId in the path. Returns a specific secret by name. The secret value is always masked.

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
`secretName`	string	Yes	The name of the secret

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>/secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Secret details (value is masked)
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
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 admin or owner role required. 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 or secret not found
500Internal Server Error
Internal server error

Delete a secret

DELETE/v1/orgs/{orgId}/projects/{projectId}/secrets/{secretName}

The org is orgId in the path. Permanently deletes a secret by name.

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
`secretName`	string	Yes	The name of the secret

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 -X DELETE "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

204No Content
Secret deleted successfully
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. 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 or secret not found
500Internal Server Error
Internal server error

List the organization secrets linked to a project

GET/v1/orgs/{orgId}/projects/{projectId}/org-secrets

The org is orgId in the path. Returns the organization secrets this project receives at deploy time. Values are always masked. shadowed is true when a project secret has the same name; the project secret is the one delivered.

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>/org-secrets" \
  -H "Authorization: Bearer <token>"

Responses

200OK
The linked organization secrets, masked
application/json
- org_secretsarray of object
  6 properties
  idinteger
  Unique identifier for the secret
  namestring
  Name of the secret
  valuestring
  Always masked with asterisks
  created_atstring (date-time)
  Timestamp when the secret was created
  updated_atstring (date-time)
  Timestamp when the secret was last updated
  shadowedboolean
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 (requires secrets:read) or the viewer role. 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

Link an organization secret to a project

PUT/v1/orgs/{orgId}/projects/{projectId}/org-secrets/{secretName}

The org is orgId in the path. Makes the named organization secret available to the project at deploy time. Linking a secret that is already linked changes nothing. The project's own secrets are not changed; a project secret with the same name takes precedence.

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
`secretName`	string	Yes	The name of the organization secret

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 -X PUT "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/org-secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
The secret was already linked
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
201Created
The secret was linked
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
400Bad Request
Invalid project ID or secret name. 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 (requires secrets:write) or the viewer role. 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 or organization secret not found
409Conflict
The project already links the maximum of 1000 organization secrets (code: org_secret_link_limit)
429Too Many Requests
Another link change is in progress for this project. Try again.
500Internal Server Error
Internal server error
503Service Unavailable
Failed to link the organization secret. Try again.

Unlink an organization secret from a project

DELETE/v1/orgs/{orgId}/projects/{projectId}/org-secrets/{secretName}

The org is orgId in the path. Stops delivering the named organization secret to the project from its next deploy. The secret itself is kept.

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
`secretName`	string	Yes	The name of the organization secret

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 -X DELETE "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/org-secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

204No Content
The secret was unlinked
400Bad Request
Invalid project ID or secret name. 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 (requires secrets:write) or the viewer role. 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 or organization secret not found, or the secret is not linked to the project
429Too Many Requests
Another link change is in progress for this project. Try again.
500Internal Server Error
Internal server error
503Service Unavailable
Failed to unlink the organization secret. Try again.

List secrets

GET/v1/apps/{appId}/secretsDeprecated

Legacy alias of /v1/projects/{projectId}/secrets — projects were previously called apps. Returns all secrets for the specified project. Secret values are always masked.

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>/secrets" \
  -H "Authorization: Bearer <token>"

Responses

200OK
List of secrets
application/json
- secretsarray of object
  5 properties
  idinteger
  Unique identifier for the secret
  namestring
  Name of the secret
  valuestring
  Always masked with asterisks
  created_atstring (date-time)
  Timestamp when the secret was created
  updated_atstring (date-time)
  Timestamp when the secret was last updated
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or viewer role cannot perform write operations
404Not Found
Project not found
500Internal Server Error
Internal server error

Create or update a secret

POST/v1/apps/{appId}/secretsDeprecated

Legacy alias of /v1/projects/{projectId}/secrets — projects were previously called apps. Creates a new secret or updates an existing secret with the same name. The secret value is encrypted at rest.

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

Required

application/json

namestringRequired
Secret name (must start with a letter or underscore, alphanumeric and underscores only)
- Pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
valuestringRequired
Secret value (will be encrypted at rest)

Example request

curl -X POST "https://api.spice.ai/v1/apps/<appId>/secrets" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "value": "string"
  }'

Responses

200OK
Secret created or updated successfully
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
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 a secret

GET/v1/apps/{appId}/secrets/{secretName}Deprecated

Legacy alias of /v1/projects/{projectId}/secrets/{secretName} — projects were previously called apps. Returns a specific secret by name. The secret value is always masked.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project
`secretName`	string	Yes	The name of the secret

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>/secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
Secret details (value is masked)
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope or admin or owner role required
404Not Found
Project or secret not found
500Internal Server Error
Internal server error

Delete a secret

DELETE/v1/apps/{appId}/secrets/{secretName}Deprecated

Legacy alias of /v1/projects/{projectId}/secrets/{secretName} — projects were previously called apps. Permanently deletes a secret by name.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project
`secretName`	string	Yes	The name of the secret

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 -X DELETE "https://api.spice.ai/v1/apps/<appId>/secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

204No Content
Secret deleted successfully
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope
404Not Found
Project or secret not found
500Internal Server Error
Internal server error

List the organization secrets linked to a project

GET/v1/apps/{appId}/org-secretsDeprecated

Legacy alias of /v1/projects/{projectId}/org-secrets — projects were previously called apps. Returns the organization secrets this project receives at deploy time. Values are always masked. shadowed is true when a project secret has the same name; the project secret is the one delivered.

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>/org-secrets" \
  -H "Authorization: Bearer <token>"

Responses

200OK
The linked organization secrets, masked
application/json
- org_secretsarray of object
  6 properties
  idinteger
  Unique identifier for the secret
  namestring
  Name of the secret
  valuestring
  Always masked with asterisks
  created_atstring (date-time)
  Timestamp when the secret was created
  updated_atstring (date-time)
  Timestamp when the secret was last updated
  shadowedboolean
400Bad Request
Invalid project ID
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (requires secrets:read) or the viewer role
404Not Found
Project not found
500Internal Server Error
Internal server error

Link an organization secret to a project

PUT/v1/apps/{appId}/org-secrets/{secretName}Deprecated

Legacy alias of /v1/projects/{projectId}/org-secrets/{secretName} — projects were previously called apps. Makes the named organization secret available to the project at deploy time. Linking a secret that is already linked changes nothing. The project's own secrets are not changed; a project secret with the same name takes precedence.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project
`secretName`	string	Yes	The name of the organization secret

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 -X PUT "https://api.spice.ai/v1/apps/<appId>/org-secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

200OK
The secret was already linked
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
201Created
The secret was linked
application/json
- idinteger
  Unique identifier for the secret
- namestring
  Name of the secret
- valuestring
  Always masked with asterisks
- created_atstring (date-time)
  Timestamp when the secret was created
- updated_atstring (date-time)
  Timestamp when the secret was last updated
400Bad Request
Invalid project ID or secret name
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (requires secrets:write) or the viewer role
404Not Found
Project or organization secret not found
409Conflict
The project already links the maximum of 1000 organization secrets (code: org_secret_link_limit)
429Too Many Requests
Another link change is in progress for this project. Try again.
500Internal Server Error
Internal server error
503Service Unavailable
Failed to link the organization secret. Try again.

Unlink an organization secret from a project

DELETE/v1/apps/{appId}/org-secrets/{secretName}Deprecated

Legacy alias of /v1/projects/{projectId}/org-secrets/{secretName} — projects were previously called apps. Stops delivering the named organization secret to the project from its next deploy. The secret itself is kept.

Path parameters

Name	Type	Required	Description
`appId`	integer	Yes	The ID of the project
`secretName`	string	Yes	The name of the organization secret

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 -X DELETE "https://api.spice.ai/v1/apps/<appId>/org-secrets/<secretName>" \
  -H "Authorization: Bearer <token>"

Responses

204No Content
The secret was unlinked
400Bad Request
Invalid project ID or secret name
401Unauthorized
Unauthorized
403Forbidden
Insufficient scope (requires secrets:write) or the viewer role
404Not Found
Project or organization secret not found, or the secret is not linked to the project
429Too Many Requests
Another link change is in progress for this project. Try again.
500Internal Server Error
Internal server error
503Service Unavailable
Failed to unlink the organization secret. Try again.