Update provider

PATCH/zones/{zoneId}/providers/{id}

Updates a Provider's configuration and metadata

Path ParametersExpand Collapse

zoneId: string

id: string

Body ParametersJSONExpand Collapse

client_id: optional string

OAuth 2.0 client identifier. Set to null to remove.

client_secret: optional string

OAuth 2.0 client secret (will be encrypted and stored securely). Set to null to remove.

description: optional string

Human-readable description. Must not contain HTML tags (e.g. <script>, <div>) or control characters.

maxLength2048

formatsafe-text

identifier: optional string

User specified identifier, unique within the zone. Must not contain HTML tags (e.g. <script>, <div>) or control characters.

minLength1

maxLength2048

formatsafe-text

metadata: optional unknown

Provider metadata. Set to null to remove all metadata.

name: optional string

Human-readable name. Must not contain HTML tags (e.g. <script>, <div>) or control characters.

minLength1

maxLength255

formatsafe-text

protocols: optional object { oauth2, openid }

Protocol-specific configuration. Set to null to remove all protocols.

oauth2: optional object { authorization_endpoint, authorization_parameters, authorization_resource_enabled, 10 more }

OAuth 2.0 protocol configuration. Set to null to remove all OAuth2 config.

authorization_endpoint: optional string

formaturi

authorization_parameters: optional map[string]

Custom query parameters appended to authorization redirect URLs. Set to null to unset.

authorization_resource_enabled: optional boolean

Whether to include the resource parameter in authorization requests. Set to null to unset.

authorization_resource_parameter: optional string

The resource parameter value to include in authorization requests. Defaults to "resource" when authorization_resource_enabled is true. Set to null to unset.

code_challenge_methods_supported: optional array of string

issuer: optional string

OIDC issuer URL for discovery and token validation. Cannot be set to null.

formaturi

jwks_uri: optional string

formaturi

registration_endpoint: optional string

formaturi

scope_parameter: optional string

The query parameter name for scopes in authorization requests. Defaults to "scope". Set to null to unset.

scope_separator: optional string

The separator character for scope values. Defaults to " " (space). Set to null to unset.

scopes_supported: optional array of string

token_endpoint: optional string

formaturi

token_response_access_token_pointer: optional string

Dot-separated path to the access token in the token response body. Defaults to "access_token". Set to null to unset.

openid: optional object { user_identifier_claim, userinfo_endpoint }

OpenID Connect protocol configuration. Set to null to remove all OpenID config.

user_identifier_claim: optional string

Name of a top-level string claim in this provider's ID Token to use as the user identifier on user creation. Set to null to revert to default. Changing this value does not affect existing users.

userinfo_endpoint: optional string

formaturi

ReturnsExpand Collapse

Provider = object { id, created_at, identifier, 12 more }

A Provider is a system that supplies access to Resources and allows actors (Users or Applications) to authenticate.

id: string

Unique identifier of the provider

created_at: string

Entity creation timestamp

formatdate-time

identifier: string

User specified identifier, unique within the zone

minLength1

maxLength2048

name: string

Human-readable name

minLength1

maxLength255

organization_id: string

Organization that owns this provider

owner_type: "platform" or "customer"

Who owns this provider. Platform-owned providers cannot be modified via API.

Accepts one of the following:

"platform"

"customer"

slug: string

URL-safe identifier, unique within the zone

minLength1

maxLength63

updated_at: string

Entity update timestamp

formatdate-time

zone_id: string

Zone this provider belongs to

client_id: optional string

OAuth 2.0 client identifier

client_secret_set: optional boolean

Indicates whether a client secret is configured

description: optional string

Human-readable description

maxLength2048

metadata: optional unknown

Provider metadata

protocols: optional object { oauth2, openid }

Protocol-specific configuration

oauth2: optional object { issuer, authorization_endpoint, authorization_parameters, 10 more }

OAuth 2.0 protocol configuration

issuer: string

OIDC issuer URL used for discovery and token validation.

formaturi

authorization_endpoint: optional string

formaturi

authorization_parameters: optional map[string]

Custom query parameters appended to authorization redirect URLs. Use for non-standard providers (e.g. Google prompt=consent, access_type=offline).

authorization_resource_enabled: optional boolean

Whether to include the resource parameter in authorization requests.

authorization_resource_parameter: optional string

The resource parameter value to include in authorization requests. Defaults to "resource" when authorization_resource_enabled is true.

code_challenge_methods_supported: optional array of string

jwks_uri: optional string

formaturi

registration_endpoint: optional string

formaturi

scope_parameter: optional string

The query parameter name for scopes in authorization requests. Defaults to "scope". Slack v2 uses "user_scope".

scope_separator: optional string

The separator character for scope values. Defaults to " " (space). Slack v2 uses ",".

scopes_supported: optional array of string

token_endpoint: optional string

formaturi

token_response_access_token_pointer: optional string

Dot-separated path to the access token in the token response body. Defaults to "access_token". Slack v2 uses "authed_user.access_token".

openid: optional object { user_identifier_claim, userinfo_endpoint }

OpenID Connect protocol configuration

user_identifier_claim: optional string

Name of a top-level string claim in this provider's ID Token to use as the user identifier on user creation. When not set, the user's Keycard ID is used.

userinfo_endpoint: optional string

formaturi

type: optional "external" or "keycard-vault" or "keycard-sts"

Accepts one of the following:

"external"

"keycard-vault"

"keycard-sts"

Update provider

curl https://api.keycard.ai/zones/$ZONE_ID/providers/$ID \
    -X PATCH

{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "identifier": "x",
  "name": "x",
  "organization_id": "organization_id",
  "owner_type": "platform",
  "slug": "slug",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "zone_id": "zone_id",
  "client_id": "client_id",
  "client_secret_set": true,
  "description": "description",
  "metadata": {},
  "protocols": {
    "oauth2": {
      "issuer": "https://example.com",
      "authorization_endpoint": "https://example.com",
      "authorization_parameters": {
        "foo": "string"
      },
      "authorization_resource_enabled": true,
      "authorization_resource_parameter": "authorization_resource_parameter",
      "code_challenge_methods_supported": [
        "string"
      ],
      "jwks_uri": "https://example.com",
      "registration_endpoint": "https://example.com",
      "scope_parameter": "scope_parameter",
      "scope_separator": "scope_separator",
      "scopes_supported": [
        "string"
      ],
      "token_endpoint": "https://example.com",
      "token_response_access_token_pointer": "token_response_access_token_pointer"
    },
    "openid": {
      "user_identifier_claim": "user_identifier_claim",
      "userinfo_endpoint": "https://example.com"
    }
  },
  "type": "external"
}

Returns Examples

{
  "id": "id",
  "created_at": "2019-12-27T18:11:19.117Z",
  "identifier": "x",
  "name": "x",
  "organization_id": "organization_id",
  "owner_type": "platform",
  "slug": "slug",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "zone_id": "zone_id",
  "client_id": "client_id",
  "client_secret_set": true,
  "description": "description",
  "metadata": {},
  "protocols": {
    "oauth2": {
      "issuer": "https://example.com",
      "authorization_endpoint": "https://example.com",
      "authorization_parameters": {
        "foo": "string"
      },
      "authorization_resource_enabled": true,
      "authorization_resource_parameter": "authorization_resource_parameter",
      "code_challenge_methods_supported": [
        "string"
      ],
      "jwks_uri": "https://example.com",
      "registration_endpoint": "https://example.com",
      "scope_parameter": "scope_parameter",
      "scope_separator": "scope_separator",
      "scopes_supported": [
        "string"
      ],
      "token_endpoint": "https://example.com",
      "token_response_access_token_pointer": "token_response_access_token_pointer"
    },
    "openid": {
      "user_identifier_claim": "user_identifier_claim",
      "userinfo_endpoint": "https://example.com"
    }
  },
  "type": "external"
}