Management APIs / Secrets

Link an organization secret to a project

PUThttps://api.spice.ai/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.

Authorizations

  • AuthorizationstringRequired

    Bearer <token>. Authentication lists the tokens it accepts.

Path parameters

  • projectIdintegerRequired

    The ID of the project

  • secretNamestringRequired

    The name of the organization secret

Header parameters

  • X-Org-Namestring

    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}$

Responses

200The secret was already linkedapplication/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

201The secret was linkedapplication/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

400Invalid project ID or secret name

401Unauthorized

403Insufficient scope (requires secrets:write) or the viewer role

404Project or organization secret not found

409The project already links the maximum of 1000 organization secrets (code: org_secret_link_limit)

429Another link change is in progress for this project. Try again.

500Internal server error

503Failed to link the organization secret. Try again.

curl -X PUT "https://api.spice.ai/v1/projects/<projectId>/org-secrets/<secretName>" \
  -H "Authorization: Bearer <token>"
{
  "id": 0,
  "name": "string",
  "value": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

application/json

PUThttps://api.spice.ai/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.

Authorizations

  • AuthorizationstringRequired

    Bearer <token>. Authentication lists the tokens it accepts.

Path parameters

  • orgIdintegerRequired

    The org id from GET /v1/orgs

    • Minimum: 1

  • projectIdintegerRequired

    The ID of the project

  • secretNamestringRequired

    The name of the organization secret

Header parameters

  • X-Org-Namestring

    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}$

Responses

200The secret was already linkedapplication/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

201The secret was linkedapplication/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

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

404Project or organization secret not found

409The project already links the maximum of 1000 organization secrets (code: org_secret_link_limit)

429Another link change is in progress for this project. Try again.

500Internal server error

503Failed to link the organization secret. Try again.

curl -X PUT "https://api.spice.ai/v1/orgs/<orgId>/projects/<projectId>/org-secrets/<secretName>" \
  -H "Authorization: Bearer <token>"
{
  "id": 0,
  "name": "string",
  "value": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

application/json

PUThttps://api.spice.ai/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.

Authorizations

  • AuthorizationstringRequired

    Bearer <token>. Authentication lists the tokens it accepts.

Path parameters

  • appIdintegerRequired

    The ID of the project

  • secretNamestringRequired

    The name of the organization secret

Header parameters

  • X-Org-Namestring

    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}$

Responses

200The secret was already linkedapplication/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

201The secret was linkedapplication/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

400Invalid project ID or secret name

401Unauthorized

403Insufficient scope (requires secrets:write) or the viewer role

404Project or organization secret not found

409The project already links the maximum of 1000 organization secrets (code: org_secret_link_limit)

429Another link change is in progress for this project. Try again.

500Internal server error

503Failed to link the organization secret. Try again.

OpenAPIapi.spice.ai/openapi.json

curl -X PUT "https://api.spice.ai/v1/apps/<appId>/org-secrets/<secretName>" \
  -H "Authorization: Bearer <token>"
{
  "id": 0,
  "name": "string",
  "value": "string",
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

application/json