Change an identity provider, keeping its sign-in URLs

PATCH

/v1/auth/providers/{providerId}

const url = 'https://example.com/v1/auth/providers/example';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"providerId":"example","kind":"oidc","displayName":"example","domains":["example"],"join":"invite","metadata":{},"issuer":"https://example.com","clientId":"example","clientSecretRef":"example","scopes":["example"],"authorizationEndpoint":"https://example.com","tokenEndpoint":"https://example.com","userinfoEndpoint":"https://example.com","jwksEndpoint":"https://example.com","claimMapping":{"userId":"example","email":"example","displayName":"example","scopes":{"claim":"example","delimiter":"example"},"metadata":["example"]},"idpMetadataXml":"example","idpEntityId":"example","idpSsoUrl":"https://example.com","idpCertificates":["example"],"spSigningKeyRef":"example","spDecryptionKeyRef":"example","wantAssertionsSigned":true,"attributeMapping":{"userId":"example","email":"example","displayName":"example"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request PATCH \
  --url https://example.com/v1/auth/providers/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "providerId": "example", "kind": "oidc", "displayName": "example", "domains": [ "example" ], "join": "invite", "metadata": {}, "issuer": "https://example.com", "clientId": "example", "clientSecretRef": "example", "scopes": [ "example" ], "authorizationEndpoint": "https://example.com", "tokenEndpoint": "https://example.com", "userinfoEndpoint": "https://example.com", "jwksEndpoint": "https://example.com", "claimMapping": { "userId": "example", "email": "example", "displayName": "example", "scopes": { "claim": "example", "delimiter": "example" }, "metadata": [ "example" ] }, "idpMetadataXml": "example", "idpEntityId": "example", "idpSsoUrl": "https://example.com", "idpCertificates": [ "example" ], "spSigningKeyRef": "example", "spDecryptionKeyRef": "example", "wantAssertionsSigned": true, "attributeMapping": { "userId": "example", "email": "example", "displayName": "example" } }'

Merges the changes into the stored provider and checks the result as a registration is (400 invalid-provider-config; 422 identity-provider-invalid when the deployment can’t use it). The provider keeps its signIn, so nothing changes on the identity provider’s side. Not mounted when the deployment can’t update providers.

Authorizations

bearerAuth

Parameters

Path Parameters

providerId

required

string

>= 1 characters

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

Request Body^required

application/json

Changes to a registered identity provider: a field given replaces the stored one, null removes an optional one, and anything not given stays. The result must still be a whole provider of its kind (the fields IdentityProviderConfig requires for it), checked as a registration is. providerId and kind can’t change; signIn is the deployment’s and is ignored. A new issuer drops the endpoints discovered from the old one.

object

>= 1 properties

providerId

Must match the path when given.

string

>= 1 characters

kind

oidc: an OpenID Connect identity provider people sign in with (Okta, Entra ID, Google, Keycloak…); its endpoints come from its discovery document. saml: a SAML 2.0 identity provider people sign in with.

string

Allowed values: oidc saml

displayName

string | null

>= 1 characters

domains

One of:

Array<string>
null

Array<string>

join

One of:

string
null

string

Allowed values: invite domain

metadata

One of:

object
null

object

key

additional properties

any

issuer

string format: uri

clientId

string

>= 1 characters

clientSecretRef

Opaque reference resolved server-side. Never a plaintext secret.

string

>= 1 characters

scopes

One of:

Array<string>
null

Array<string>

authorizationEndpoint

string | null format: uri

tokenEndpoint

string | null format: uri

userinfoEndpoint

string | null format: uri

jwksEndpoint

string | null format: uri

claimMapping

One of:

object
null

Per-provider claim mapping. All fields optional; closer to OIDC defaults (sub/email/name) → fewer overrides needed.

object

userId

string

>= 1 characters

email

string

>= 1 characters

displayName

string

>= 1 characters

scopes

Claim path + optional delimiter for extracting Kindgi OAuth scopes from provider claims. When absent, scopes come from the token response scope field instead.

object

claim

required

string

>= 1 characters

delimiter

string

metadata

Array<string>

idpMetadataXml

string | null

>= 1 characters

idpEntityId

string | null

>= 1 characters

idpSsoUrl

string | null format: uri

idpCertificates

One of:

Array<string>
null

Array<string>

spSigningKeyRef

string | null

>= 1 characters

spDecryptionKeyRef

string | null

>= 1 characters

wantAssertionsSigned

boolean | null

attributeMapping

One of:

object
null

object

userId

string

>= 1 characters

email

string

>= 1 characters

displayName

string

>= 1 characters

Responses

200

Updated.

application/json

object

providerId

required

string

>= 1 characters

provider

required

One of: discriminator: kind

object
object

An OpenID Connect identity provider people sign in with. The endpoints come from the issuer’s discovery document when absent, and are returned once the deployment has them.

object

providerId

required

string

>= 1 characters

displayName

The name a sign-in page shows (“Sign in with …”). Default: providerId.

string

>= 1 characters

domains

The email domains whose people sign in with this provider (lowercase, e.g. acme.com): how an email-first sign-in page finds it.

Array<string>

join

Who may sign in the first time: invite (default) only people a tenant admin added; domain also anyone from one of domains, once the deployment has verified them.

string

Allowed values: invite domain

signIn

One of:

object
object

object

redirectUri

required

string format: uri

metadata

object

key

additional properties

any

kind

required

string

Allowed value: oidc

issuer

required

string format: uri

clientId

required

string

>= 1 characters

clientSecretRef

required

Opaque reference resolved server-side. Never a plaintext secret.

string

>= 1 characters

scopes

Default openid email profile.

Array<string>

authorizationEndpoint

string format: uri

tokenEndpoint

string format: uri

userinfoEndpoint

string format: uri

jwksEndpoint

string format: uri

claimMapping

Per-provider claim mapping. All fields optional; closer to OIDC defaults (sub/email/name) → fewer overrides needed.

object

userId

string

>= 1 characters

email

string

>= 1 characters

displayName

string

>= 1 characters

scopes

Claim path + optional delimiter for extracting Kindgi OAuth scopes from provider claims. When absent, scopes come from the token response scope field instead.

object

claim

required

string

>= 1 characters

delimiter

string

metadata

Array<string>

A SAML 2.0 identity provider people sign in with: its metadata XML, or its entity ID, single sign-on URL and signing certificates. Keys are given as references, never as keys.

object

providerId

required

string

>= 1 characters

displayName

The name a sign-in page shows (“Sign in with …”). Default: providerId.

string

>= 1 characters

domains

The email domains whose people sign in with this provider (lowercase, e.g. acme.com): how an email-first sign-in page finds it.

Array<string>

join

Who may sign in the first time: invite (default) only people a tenant admin added; domain also anyone from one of domains, once the deployment has verified them.

string

Allowed values: invite domain

signIn

One of:

object
object

object

redirectUri

required

string format: uri

metadata

object

key

additional properties

any

kind

required

string

Allowed value: saml

idpMetadataXml

string

>= 1 characters

idpEntityId

string

>= 1 characters

idpSsoUrl

The IdP’s single sign-on URL (HTTP-Redirect binding).

string format: uri

idpCertificates

The IdP’s signing certificates (PEM); several during a rollover.

Array<string>

spSigningKeyRef

Opaque reference to the service provider’s signing key, for IdPs that require signed AuthnRequests. Never a plaintext key.

string

>= 1 characters

spDecryptionKeyRef

Opaque reference to the key that decrypts encrypted assertions. Never a plaintext key.

string

>= 1 characters

wantAssertionsSigned

Require signed assertions. Default true.

boolean

attributeMapping

Assertion attribute names. Defaults: userId = the NameID, email = email.

object

userId

string

>= 1 characters

email

string

>= 1 characters

displayName

string

>= 1 characters

Example

{
  "provider": {
    "join": "invite",
    "kind": "oidc"
  }
}

400

Malformed request body.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Not a tenant admin (permission-denied), or this deployment’s operator manages sign-in (identity-providers-operator-managed, KINDGI_AUTH_TENANT_PROVIDERS=off): only the deployment’s own token can change its providers.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

No identity provider registered with that id under this tenant.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Idempotency-Key was reused with a different body, or resource-state conflict.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

422

The deployment could not use the configuration (identity-provider-invalid).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Server error (unmapped domain code or framework crash).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

Change an identity provider, keeping its sign-in URLs

Authorizations

Parameters

Path Parameters

Header Parameters

Request Bodyrequired

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

422

Examplegenerated

500

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated