Update Provider Key

PATCH /provider_keys/{provider_key_id}

Update Provider Key

Update selected provider key fields, including the upstream secret. Send api_key (or config, for a multi-field credential) to rotate the secret in place: every model that references this provider key picks up the new credential, with no model or caller change. Omit those fields to leave the stored secret untouched.

Parameters

• provider_key_id (path, string, required): Provider key ID.

Request body

Content type: application/json

• display_name (string, optional): Human-readable provider key name.

• api_key (string, optional): Replacement plaintext upstream API key. Omit the field to keep the stored key; read endpoints never return it, so there is no value to echo back. The new value is encrypted before storage and projected to every environment allowed to use this provider key. Providers whose credential has more than one field use config instead.

• config (object, optional): Replacement structured credential, for providers that need more than one secret field. Omit the field to keep the stored credential. The whole credential is replaced, so supply every field the provider requires, not only the ones being rotated.

• api_base (string, optional): Upstream endpoint override for this provider key. Empty values clear the override only when the provider has a fallback endpoint. BYO provider keys must keep an explicit endpoint.

• allowed_environments (array, optional): Replacement list of environments that may reference this provider key.

• adapter (string, optional): Protocol adapter for BYO provider keys. PATCH recognizes this field so the API can return an immutable-field error, but the adapter cannot be changed after creation.

• apis (object, optional): Replacement set of native API surfaces. null clears the declaration, returning the key to provider- and adapter-derived behaviour; {} declares that the endpoint serves nothing beyond its adapter's own surface, which is what turns off the /v1/responses passthrough.

• allOf variant 1

• apis.responses (object, optional): Where one API surface is served. An entry with no base still carries the declaration that the surface exists — it is served at api_base like everything else.

• apis.responses.base (string, optional): Absolute http or https base URL this surface is served at, when it differs from api_base. Same shape rules as api_base: no credentials, query string or fragment. A pasted full endpoint URL is stored as given and the gateway trims the endpoint path when it builds the upstream URL, exactly as it does for api_base.

• apis.messages (object, optional): Where one API surface is served. An entry with no base still carries the declaration that the surface exists — it is served at api_base like everything else.

• apis.messages.base (string, optional): Absolute http or https base URL this surface is served at, when it differs from api_base. Same shape rules as api_base: no credentials, query string or fragment. A pasted full endpoint URL is stored as given and the gateway trims the endpoint path when it builds the upstream URL, exactly as it does for api_base.

• strip_headers (array, optional): Per-key passthrough header-strip override. An empty array strips nothing, and a non-empty list strips exactly those headers.

• request (object, optional): Per-provider-key request-transformation overrides. Field-name / header-name grammar, reserved-header protection, and the temperature_max >= temperature_min cross-check are validated by the API.

• request.param_renames (object, optional): Map of inbound param name to upstream param name.

• request.param_constraints (object, optional): Temperature clamp. temperature_max must be greater than or equal to temperature_min.

• request.param_constraints.temperature_max (number, optional): Maximum allowed temperature value after clamping.

• request.param_constraints.temperature_min (number, optional): Minimum allowed temperature value after clamping.

• request.default_headers (object, optional): Extra request headers injected upstream. Values may reference the request context with ${...} variables — request.id, request.api_key.id, request.api_key.name, request.api_key.team_id, request.api_key.user_id, model.id, model.name, provider_key.id, provider_key.name. An unknown variable is rejected here; a variable with no value for a given request drops that header from that request rather than sending it blank. The API rejects the following header names case-insensitively: authorization, x-api-key, x-goog-api-key, api-key, x-amz-security-token, x-amz-date, x-amz-content-sha256, proxy-authorization, cookie, and host. For Amazon Bedrock provider keys, the gateway also ignores x-amz-target and x-amzn-bedrock-accept, which its Bedrock integration owns.

• request.forward_client_headers (array, optional): Inbound client headers forwarded to the upstream provider, as exact header names or single-* globs (anthropic-beta, x-trace-*), matched case-insensitively. Empty (the default) forwards nothing. Authentication, transport, and gateway-owned (x-aisix-*) headers are rejected here and never forwarded regardless of the patterns.

• request.default_body_fields (object, optional): Extra JSON body fields merged into the upstream request.

• response (object, optional): Per-provider-key response-transformation overrides.

• response.stream_done_marker (string, optional): Expected handling of the terminal data: [DONE] marker in an upstream SSE response. A mismatch is logged but does not fail a stream whose chunks were already delivered.

• response.content_list_to_string (boolean, optional): Whether to flatten list-shaped content into a string.

• response.error_envelope (string, optional): Stored error-envelope preference for compatibility. The gateway does not currently apply this setting.

• response.reasoning_field (string, optional): Dot-separated path to the upstream reasoning field.

• tls (object, optional): Replacement TLS settings, replaced whole like request. null or an empty object clears the override, so the endpoint falls back to the gateway's deployment-wide trust settings. Omit the field to leave the stored settings alone.

• allOf variant 1

• tls.ca_cert (string, optional): PEM-encoded certificate authority certificates trusted as issuers for this endpoint, in addition to the gateway's default trust store. A bundle containing several certificates is accepted. An empty value clears it.

• tls.verify (boolean, optional): Whether the endpoint's certificate is verified. Setting this to false accepts any certificate, including one presented by an intercepting party, and is intended only for test environments.

Responses

• 200: OK

• provider_key (object, required): Provider key details returned by get and update operations. Detail responses can include the configured upstream endpoint override.

• provider_key.id (string, required): Provider key ID.

• provider_key.org_id (string, required): Organization ID that owns this provider key.

• provider_key.provider (string, required): Upstream provider identifier.

• provider_key.display_name (string, required): Human-readable provider key name.

• provider_key.allowed_environments (array, required): Environments that can use this provider key when creating model resources. An empty array makes the key unavailable to all environments.

• provider_key.byo_adapter (string, optional): Protocol adapter used by BYO provider keys.

• provider_key.apis (object, optional): API surfaces this endpoint serves natively, beyond the one its protocol adapter already implies, and the base URL each one lives at.

One upstream account often exposes more than one protocol, on different paths of the same host — an OpenAI-compatible /v1/chat/completions under /v1 and an Anthropic-compatible /v1/messages under /anthropic, both authenticated by the same credential. api_base names only one of them, so without this field every request the declared path cannot serve is translated instead, losing what the target protocol carries and the chat shape does not — Anthropic prompt-cache breakpoints and thinking blocks. Declaring the second entry lets each inbound protocol reach its own native path under the one credential, so callers speaking different protocols address the same model by one name.

The two surfaces resolve on their own terms:

• messages is additive. A key whose adapter is anthropic serves it at api_base whatever this object says; listing it adds the route to a key whose adapter is something else.
• responses is authoritative once this object is present: /v1/responses is forwarded natively only if listed. Omitting it states that the endpoint has no such route, and the gateway translates the request to chat completions rather than forwarding one the endpoint answers with 404. This is the setting for an OpenAI-compatible endpoint — vLLM, an internal relay — reached through the openai provider with a custom api_base.

Omit the whole object to keep the behaviour a key has without it: the provider decides /v1/responses and the adapter decides /v1/messages.

Not accepted on the bedrock, vertex or azure-openai adapters: those platforms' native routes are not these paths at all, so every request reaches them translated and nothing here would take effect.

Surfaces this object has no field for — embeddings, audio, images, videos, files, batches, fine-tuning, rerank — always use api_base.

• provider_key.apis.responses (object, optional): Where one API surface is served. An entry with no base still carries the declaration that the surface exists — it is served at api_base like everything else.

• provider_key.apis.responses.base (string, optional): Absolute http or https base URL this surface is served at, when it differs from api_base. Same shape rules as api_base: no credentials, query string or fragment. A pasted full endpoint URL is stored as given and the gateway trims the endpoint path when it builds the upstream URL, exactly as it does for api_base.

• provider_key.apis.messages (object, optional): Where one API surface is served. An entry with no base still carries the declaration that the surface exists — it is served at api_base like everything else.

• provider_key.apis.messages.base (string, optional): Absolute http or https base URL this surface is served at, when it differs from api_base. Same shape rules as api_base: no credentials, query string or fragment. A pasted full endpoint URL is stored as given and the gateway trims the endpoint path when it builds the upstream URL, exactly as it does for api_base.

• provider_key.apis_source (string, optional): Who declared the surfaces in apis. catalog means AISIX resolved them from its curated entry for this provider, so the key reaches the vendor's own routes without anyone configuring it; operator means they were set on this key. Absent when there is no declaration.

The distinction is what lets AISIX correct a curated entry later without overwriting a declaration you chose: a key whose source is operator is never rewritten. Setting apis makes it yours; clearing it with null returns the key to the curated entry, where one exists.

• provider_key.strip_headers (array, required): Request headers stripped before forwarding traffic upstream. Null values use the default credential-header strip set. An empty array strips nothing.

• provider_key.telemetry_label (string, required): Stable provider-key label used in usage and log records.

• provider_key.api_base (string, optional): Upstream endpoint override. Absent values mean the provider default is used.

• provider_key.created_at (string, required): Time when the provider key was created.

• provider_key.updated_at (string, required): Time when the provider key was last updated.

• provider_key.request (object, optional): Per-provider-key request-transformation overrides. Field-name / header-name grammar, reserved-header protection, and the temperature_max >= temperature_min cross-check are validated by the API.

• provider_key.request.param_renames (object, optional): Map of inbound param name to upstream param name.

• provider_key.request.param_constraints (object, optional): Temperature clamp. temperature_max must be greater than or equal to temperature_min.

• provider_key.request.param_constraints.temperature_max (number, optional): Maximum allowed temperature value after clamping.

• provider_key.request.param_constraints.temperature_min (number, optional): Minimum allowed temperature value after clamping.

• provider_key.request.default_headers (object, optional): Extra request headers injected upstream. Values may reference the request context with ${...} variables — request.id, request.api_key.id, request.api_key.name, request.api_key.team_id, request.api_key.user_id, model.id, model.name, provider_key.id, provider_key.name. An unknown variable is rejected here; a variable with no value for a given request drops that header from that request rather than sending it blank. The API rejects the following header names case-insensitively: authorization, x-api-key, x-goog-api-key, api-key, x-amz-security-token, x-amz-date, x-amz-content-sha256, proxy-authorization, cookie, and host. For Amazon Bedrock provider keys, the gateway also ignores x-amz-target and x-amzn-bedrock-accept, which its Bedrock integration owns.

• provider_key.request.forward_client_headers (array, optional): Inbound client headers forwarded to the upstream provider, as exact header names or single-* globs (anthropic-beta, x-trace-*), matched case-insensitively. Empty (the default) forwards nothing. Authentication, transport, and gateway-owned (x-aisix-*) headers are rejected here and never forwarded regardless of the patterns.

• provider_key.request.default_body_fields (object, optional): Extra JSON body fields merged into the upstream request.

• provider_key.response (object, optional): Per-provider-key response-transformation overrides.

• provider_key.response.stream_done_marker (string, optional): Expected handling of the terminal data: [DONE] marker in an upstream SSE response. A mismatch is logged but does not fail a stream whose chunks were already delivered.

• provider_key.response.content_list_to_string (boolean, optional): Whether to flatten list-shaped content into a string.

• provider_key.response.error_envelope (string, optional): Stored error-envelope preference for compatibility. The gateway does not currently apply this setting.

• provider_key.response.reasoning_field (string, optional): Dot-separated path to the upstream reasoning field.

• provider_key.tls (object, optional): TLS settings for connections to one provider key's endpoint.

Use this when a single endpoint needs different trust settings from the rest — typically a self-hosted model endpoint whose certificate is signed by a private certificate authority. For a certificate authority that applies to every upstream, configure it on the gateway instead.

• provider_key.tls.ca_cert (string, optional): PEM-encoded certificate authority certificates trusted as issuers for this endpoint, in addition to the gateway's default trust store. A bundle containing several certificates is accepted. An empty value clears it.

• provider_key.tls.verify (boolean, optional): Whether the endpoint's certificate is verified. Setting this to false accepts any certificate, including one presented by an intercepting party, and is intended only for test environments.

• warnings (array, optional): Present on save operations when some data plane nodes in the environments this provider key is allowed in run a gateway version that will not execute part of the saved configuration — a declared API surface an older data plane ignores, for instance. Never present on reads.

• warnings[].code (string, required): How affected nodes treat the saved resource. field_ignored: the resource stays in service on those nodes but the named field has no effect there — beware when the field is restrictive, since the restriction is silently not enforced. row_rejected: those nodes refuse the whole resource, so it stops serving there entirely (or, if a previously accepted version exists, they keep serving the old values).

• warnings[].field (string, required): Dot-separated path of the field that triggered the warning, as delivered to gateway nodes.

• warnings[].min_dp_version (string, required): Oldest gateway version that fully executes the field. The literal value unreleased means no released gateway version executes it yet.

• warnings[].affected_dp_count (integer, required): Number of currently registered nodes in the environment running an older gateway version than min_dp_version.

• warnings[].affected_dp_versions (array, required): Distinct gateway versions reported by the affected nodes, capped at five entries. Nodes that report no version appear as unknown.

• 400: Request body or parameters failed validation.

• error (object, required): Error details.

• error.code (string, required): Machine-readable identifier. Examples: UNAUTHENTICATED, INVALID_REQUEST, MASTER_KEY_UNSET, INTERNAL.

• error.message (string, required): Human-readable explanation; safe to surface to operators.

• 401: Missing or invalid bearer. Response fields (application/json): identical to PATCH /provider_keys/{provider_key_id}, response 400 above.

• 403: Authenticated request is not permitted. Response fields (application/json): identical to PATCH /provider_keys/{provider_key_id}, response 400 above.

• 404: Resource not found. Response fields (application/json): identical to PATCH /provider_keys/{provider_key_id}, response 400 above.

• 409: Request conflicts with current resource state. Response fields (application/json): identical to PATCH /provider_keys/{provider_key_id}, response 400 above.

cURL

curl -X PATCH '$AISIX_CP/provider_keys/{provider_key_id}' -H 'Authorization: Bearer $AISIX_TOKEN'