Create an SSO connection

POST

/api/v1/team/sso/connections

curl --request POST \
  --url https://api.deploybase.eu/api/v1/api/v1/team/sso/connections \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "client_id": "example", "client_secret": "example", "is_id_token_mapping": true, "issuer": "example", "name": "example", "scopes": [ "example" ], "trust_unverified_email": true }'

Validates the issuer against OpenID Connect Discovery 1.0, registers the provider inside the team’s Zitadel organization, and puts it on the sign-in screen. The issuer stored is the one the provider reports for itself, which can differ from the submitted value by a trailing slash; data.warnings carries anything the admin should know about the provider’s metadata. Nothing is created anywhere when discovery fails. The client secret is encrypted at rest and never returned. Team admin or owner.

Authorizations

• BearerAuth

Request Body

Connection to create

Media type application/json

object

client_id

string

client_secret

string

is_id_token_mapping

IsIDTokenMapping is a pointer so an omitted field can mean “you decide”: the service turns it on for Keycloak, whose signed-userinfo setting is undetectable and breaks the broker, and always turns it on for a provider with no userinfo endpoint. Sending false explicitly keeps userinfo unless that second rule applies.

boolean

issuer

string

name

string

scopes

Array<string>

trust_unverified_email

TrustUnverifiedEmail lets this provider’s addresses match a user even when it does not report them as verified. Off unless the admin asks for it.

boolean

Example ^generated

{
  "client_id": "example",
  "client_secret": "example",
  "is_id_token_mapping": true,
  "issuer": "example",
  "name": "example",
  "scopes": [
    "example"
  ],
  "trust_unverified_email": true
}

Responses

201

Created

Media type application/json

object

data

meta

object

request_id

string

timestamp

string

trace_id

string

data

object

client_id

string

created_at

string

has_client_secret

boolean

id

string

is_active

boolean

is_id_token_mapping

boolean

issuer

string

name

string

provider

string

redirect_uri

RedirectURI is the callback the admin must register in their own IdP. It is Zitadel’s, not ours, and it is the same for every connection — which is exactly why it rides on every view instead of living in the frontend: the value depends on which Zitadel this deployment talks to, and a hard-coded copy would be wrong on every other environment.

string

scopes

Array<string>

trust_unverified_email

TrustUnverifiedEmail is the admin’s statement that this provider’s addresses may be used to match a user even when it does not report them as verified. Stored and returned in phase 1; read by phase 2 matching.

boolean

updated_at

string

warnings

Warnings are the discovery advisories for the issuer, present only on the responses to Create and Update — the two moments the admin is looking at the form and can still act on them. A list or a get does not re-fetch the issuer.

Array<object>

object

code

string

docs_url

string

message

string

Example ^generated

{
  "data": {
    "client_id": "example",
    "created_at": "example",
    "has_client_secret": true,
    "id": "example",
    "is_active": true,
    "is_id_token_mapping": true,
    "issuer": "example",
    "name": "example",
    "provider": "example",
    "redirect_uri": "example",
    "scopes": [
      "example"
    ],
    "trust_unverified_email": true,
    "updated_at": "example",
    "warnings": [
      {
        "code": "example",
        "docs_url": "example",
        "message": "example"
      }
    ]
  },
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

400

Bad Request

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

401

Unauthorized

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

403

Forbidden

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

422

INVALID_INPUT, SSO_ISSUER_INVALID, SSO_ISSUER_UNREACHABLE, SSO_ISSUER_MISMATCH or SSO_DISCOVERY_INCOMPLETE

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

502

SSO_PROVIDER_ERROR

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

503

SSO_NOT_CONFIGURED

Media type application/json

object

code

string

details

error

string

meta

object

request_id

string

timestamp

string

trace_id

string

Example ^generated

{
  "code": "example",
  "details": "example",
  "error": "example",
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}