Skip to content
Kindgi

Complete an OAuth/OIDC callback

POST
/v1/auth/callback/{providerId}
curl --request POST \
  --url https://example.com/v1/auth/callback/example \
  --header 'Content-Type: application/json' \
  --data '{ "code": "example", "state": "example" }'

Public — the caller has not yet obtained a session token. Verifies state, exchanges code for provider tokens via the deployment’s exchangeCode, fetches userinfo, and persists a session via SessionStoreBinding. Returns an opaque kgi_sk_* session token the caller uses on subsequent requests. The underlying provider access-token never leaves the server. When the provider config populated allowedRedirectUris, the stored redirect_uri is re-checked against the current allowlist — a mismatch (allowlist tightened between login and callback) returns 400 redirect-uri-mismatch.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
providerId
required
string
>= 1 characters

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
code
required
string
>= 1 characters
state
required
string
>= 1 characters
Examplegenerated
{
  "code": "example",
  "state": "example"
}

Responses

Section titled “Responses”

201

Section titled “201”

Session created.

Media typeapplication/json
object
sessionToken
required

Opaque framework-issued session token (kgi_sk_<sessionId>). Send as Authorization: Bearer <sessionToken> on subsequent requests. The underlying provider access-token never leaves the server.

string
sessionId
required
string
expiresAt
required
string format: date-time
Examplegenerated
{
  "sessionToken": "example",
  "sessionId": "example",
  "expiresAt": "2026-04-15T12:00:00Z"
}

400

Section titled “400”

Malformed body or state unknown/expired/consumed.

Media typeapplication/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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

422

Section titled “422”

Code exchange with the provider failed.

Media typeapplication/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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}