API reference, Console auth

Exchange a Google ID token for an app session (native apps)

View as Markdown

POST/v1/console/auth/google/tokenoperation id createGoogleSession

For the native apps (iOS and Android), which sign in with Google on the device. The gateway verifies the Google ID token (RS256 with Google's published keys, issuer, audience = any of Dex's Google client ids, expiry, and nonce when given) and requires an email address Google has verified. The address is treated exactly like a signed-in email code: an existing account with that address is signed in, otherwise a new account is created. The answer is a bearer AppSession: no cookie and no CSRF token. At most 60 Google sign-ins per client network per hour, together with startGoogleSignIn.

Authentication. None. This route is public.

Request body

application/json, schema GoogleTokenRequest

id_tokenstringrequired

The Google ID token (a JWT) from Google Sign-In on the device.

at most 4,096 characters
pattern ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$

noncestring

The nonce the app passed to Google Sign-In. When given, the token's nonce claim must equal it.

1 to 128 characters

Responses

200Signed in with a bearer app session.

Headers: x-request-id

objectstringrequired

always "app_session"

account_idAccountIdrequired

pattern ^acc_[0-9A-HJKMNP-TV-Z]{26}$

session_tokenstringrequired

Shown once. Only its SHA-256 is stored. Keep it in the device's secure storage.

pattern ^dex_ses_[A-Za-z0-9_-]{43}$

expires_atstringrequired

30 days after sign-in; every use moves it to 30 days after that use.

format date-time

400The request could not be read. Codes: invalid_json (not JSON, not UTF-8, or a \u escape that is half of a surrogate pair, such as "\ud800" without its low half), duplicate_key (a JSON object repeats a key; param is the JSON pointer of the repeated member, such as /questions/q1/options/a), unsupported_media_type (not application/json) and invalid_header (a malformed idempotency-key or x-client-request-id; param names the header).

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

401The Google ID token did not sign anyone in. Codes: invalid_google_token (malformed, not signed by Google, wrong issuer or audience, expired, or its nonce differs from nonce) and google_email_unverified (Google has not verified the account's email address).

Headers: x-request-id

Error envelope. See Errors for every type and code.

403The credentials are valid but not allowed to do this (missing scope, suspended account or failed CSRF check).

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

422The request is well-formed JSON but breaks a validation rule. param names the field as a dotted path. Codes: unknown_field, missing_field, invalid_type (wrong JSON type), invalid_value (right type, value out of range: an empty or over-long string, a state, instructions, criteria string or option description of only whitespace, an empty questions or options object, an empty state object or array, a pattern or allowed-value mismatch such as a label or level with outer whitespace, a state nested deeper than 32 levels, a bad date or date range), field_not_allowed (options or levels on the wrong question type), invalid_question_id, too_many_questions, too_many_options, invalid_levels (including two levels equal after Unicode NFC normalisation and lower-casing), invalid_min_confidence, duplicate_label (two option labels equal after Unicode NFC normalisation and lower-casing, such as Billing and billing), state_path_not_found, state_not_json and, on the console, top_up_limit_exceeded.

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

429sign_ins_per_hour: more than 60 Google sign-ins were started from this client network in the last hour. retry-after is the real wait until one can be started again, up to 3,600 seconds.

Headers: x-request-id, retry-after

Error envelope. See Errors for every type and code.

500An unexpected error. Any charge was refunded. Retry with the same idempotency key.

Headers: x-request-id, x-client-request-id

Error envelope. See Errors for every type and code.

503maintenance: the console's database, sign-in or payments are unavailable for a moment (for createGoogleSession also: Google sign-in is not configured, or Google's signing keys cannot be fetched). Retry after retry-after. Nothing was changed.

Headers: x-request-id, retry-after

Error envelope. See Errors for every type and code.

Examples

Illustrative values. Examples show the shape of requests and responses; the numbers in them are not measured results.

Request: token

{
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20ifQ.c2lnbmF0dXJl"
}

Response: A bearer app session (native apps)

{
  "object": "app_session",
  "account_id": "acc_01M4ZPXYG0F5KZNWJ47TAN9ZT2",
  "session_token": "dex_ses_ExampleOnly0NotAReal0SessionToken0123456789",
  "expires_at": "2026-11-19T12:00:00Z"
}