Skip to main content
POST
auth.social.exchange

Authorizations

Authorization
string
header
required

API key: sk_live_…

Headers

Idempotency-Key
string

Optional. A retry with the same key returns the stored result.

Maximum string length: 255
Pramaan-Account
string

Optional. One of your account ids (GET /v1/accounts): run on that account, whatever your routing rules say. The response header X-Pramaan-Account names the account that ran.

Pramaan-End-User
string

Optional. Your own tag for your end user: a sticky: end_user rule keeps them on the account that first served them.

Maximum string length: 256
Pramaan-End-User-Group
string

Optional. Your end user's group, matched by rules with endUserGroup.

Maximum string length: 64

Body

application/json
providerKey
string
required

Sign-in product key. Name a connected account with the Pramaan-Account header when several are connected.

Required string length: 1 - 32
Pattern: ^[a-z][a-z0-9-]*$
code
string
required

Single-use authorization code returned to your app.

Required string length: 1 - 16384
redirectUri
string
required

Exact redirect URL used when requesting the code; https or http on localhost.

Maximum string length: 2048
pkceVerifier
string

Optional one-time secret binding the code to the app that started sign-in.

Required string length: 43 - 128
Pattern: ^[A-Za-z0-9._~-]+$
expectedNonce
string

Nonce used when starting sign-in; checked against the signed token.

Required string length: 1 - 512
connectionRef
string

Only for enterprise sign-in: the connection auth.enterprise.start was called with. Then providerKey must be enterprise, and state, pkceVerifier and expectedNonce are required.

Pattern: ^(ref_[0-9A-HJKMNP-TV-Z]{26}|rh_[A-Za-z0-9_-]{24,1024})$
state
string

Only with connectionRef, and then required: the state that came back to your callback. The sign-in is redeemed only when it is the state auth.enterprise.start was called with. Without connectionRef it is refused as an unknown field.

Required string length: 22 - 512
Pattern: ^[A-Za-z0-9._~-]+$

Response

The result

providerKey
string
required

Sign-in product key; pair it with subjectId to identify an account.

subjectId
string
required

This app's identity subject from the connected sign-in account.

emailVerified
boolean
required

True only when signed evidence or the account's verified flag confirms the email.

email
string

Email address when available; personal data.

displayName
string

Display name when available; personal data.

pictureUrl
string

Short-lived picture link on platform file storage, when available.