Complete a team SSO sign-in

POST

/api/v1/auth/sso/callback

curl --request POST \
  --url https://api.deploybase.eu/api/v1/api/v1/auth/sso/callback \
  --header 'Content-Type: application/json' \
  --data '{ "intent_id": "example", "token": "example" }'

Verifies a Zitadel IdP intent, resolves which team’s provider produced it, and reports whether the person may sign in as a member of that team. Returns 201 when a member was provisioned just in time and 200 otherwise. Every refusal carries a stable code and a member-facing sentence; details.docs_url links the guide that explains the fix to a team admin. This endpoint never creates an organization and never matches an identity outside the resolved team (ADR-022). No authentication required; rate limited per IP.

Request Body

Completed IdP intent

Media type application/json

object

intent_id

IntentID is the Zitadel IdP intent id from the callback URL.

string

token

Token is that intent’s single-use token — a bearer credential. Never log it.

string

Example ^generated

{
  "intent_id": "example",
  "token": "example"
}

Responses

200

Signed in as an existing member

Media type application/json

object

data

meta

object

request_id

string

timestamp

string

trace_id

string

data

object

email

Email is the member’s address, for the post-login chrome.

string

outcome

Outcome is “linked”, “auto_linked” or “created”.

string

team_id

TeamID is the team signed into; the caller makes it the active team.

string

user_id

UserID is the Zitadel user to create a session for.

string

Example ^generated

{
  "data": {
    "email": "example",
    "outcome": "example",
    "team_id": "example",
    "user_id": "example"
  },
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

201

A new member was provisioned

Media type application/json

object

data

meta

object

request_id

string

timestamp

string

trace_id

string

data

object

email

Email is the member’s address, for the post-login chrome.

string

outcome

Outcome is “linked”, “auto_linked” or “created”.

string

team_id

TeamID is the team signed into; the caller makes it the active team.

string

user_id

UserID is the Zitadel user to create a session for.

string

Example ^generated

{
  "data": {
    "email": "example",
    "outcome": "example",
    "team_id": "example",
    "user_id": "example"
  },
  "meta": {
    "request_id": "example",
    "timestamp": "example",
    "trace_id": "example"
  }
}

400

SSO_NOT_A_MEMBER, SSO_CONNECTION_INACTIVE, SSO_JIT_DISABLED, SSO_EMAIL_UNVERIFIED, SSO_NO_EMAIL, SSO_ACCOUNT_IN_OTHER_TEAM or SSO_INTENT_INVALID

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

429

Rate limit exceeded

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_UNAVAILABLE

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