TriportRPC
DashboardDocs

GET /v1/auth/google/callback

Browser-facing OAuth callback that completes the Google sign-in dance, issues a console session, and redirects into the app.

———

This endpoint is the redirect target of the Google OAuth flow that begins at GET /v1/auth/google/start. Google sends the user's browser here with a code and state after they approve the consent screen. You never call it directly or with fetch — it is a full-page navigation that ends in a 302 redirect.

On arrival it:

  1. Validates the state query parameter against the nl_google_state cookie (constant-time compare) and confirms the nl_google_verifier (PKCE) cookie is present. Both short-lived cookies are then cleared regardless of outcome.
  2. Exchanges the authorization code (plus the PKCE verifier) for an access token, then fetches the user's profile. The account's email must be verified or the flow is rejected.
  3. Links or creates the console user, issues a session, and sets the nl_session (HttpOnly) and nl_csrf (double-submit) cookies.
  4. Redirects the browser to the configured post-login URL — /app/chains by default.

Best-effort, non-blocking hooks run during link/create: a free subscription is ensured for new users, a pending referral attribution (from a referral cookie) is applied, and a welcome email is dispatched. Failures in these hooks do not fail the sign-in.

On any error the endpoint redirects to /login?error=google_<tag> rather than rendering raw JSON, so the login page can show a localized toast. (The one exception is when Google sign-in is not configured server-side, which returns a 503 body — see Errors.)

Parameters

These are supplied by Google on the redirect; you do not construct them.

Query parametersobject
codestringrequired
Authorization code to exchange for a token.
statestringrequired
Opaque value that must match the nl_google_state cookie set at /start.
errorstringoptional
Present when the user denies consent or Google reports a problem; triggers the failure redirect.
Cookies (set earlier by /v1/auth/google/start)object
nl_google_statestringrequired
CSRF/state guard for the OAuth round-trip. HttpOnly, ~10 min TTL.
nl_google_verifierstringrequired
PKCE code verifier. HttpOnly, ~10 min TTL.

Response

There is no JSON body on the success path. The endpoint replies with a 302 Found and sets the session cookies:

On failure it instead replies:

HTTP/1.1 302 Found
Location: /login?error=google_invalid_state
Location (success)header
Post-login URL, default /app/chains.
Location (failure)header
/login?error=google_<tag>, where <tag> identifies the failure.
nl_sessioncookie
HttpOnly session cookie used to authenticate subsequent console calls.
nl_csrfcookie
Double-submit CSRF token; echo it as X-CSRF-Token on mutating requests.

Errors

Most failures are surfaced as a redirect to /login?error=google_<tag>, not as an HTTP error status. The <tag> values:

Redirect tagMeaningWhen it happens
google_invalid_requestMissing code or stateQuery parameters incomplete.
google_invalid_stateState/PKCE mismatchstate doesn't match the cookie, or a state/verifier cookie is missing.
google_exchange_failedToken exchange failedCode-for-token call to the provider errored.
google_userinfo_failedProfile fetch failedUserinfo lookup errored.
google_userinfo_incompleteProfile missing fieldsNo subject id or email returned.
google_email_unverifiedEmail not verifiedThe Google account's email is unverified.
google_session_issue_failedSession could not be issuedBackend failed to mint a session.
google_internalInternal errorLink/create user failed.
google_<provider error>Provider-reported errorGoogle returned ?error=... (e.g. user denied consent).
HTTP codeMeaningWhen it happens
503google_disabledGoogle sign-in is not configured on the server.

See the shared errors reference for the standard error envelope used elsewhere in the API.

Examples

This endpoint is reached by browser navigation, so there is no client-side call to make. The only thing your app initiates is the start of the flow, which redirects the browser to Google and ultimately back to this callback.

JavaScript (fetch)

// Kick off Google sign-in — a full-page navigation, not fetch().
// The callback below handles the rest and lands the user on /app/chains.
window.location.assign("https://api.triport.io/v1/auth/google/start");

TypeScript SDK (@triport/sdk)

import { authUrls } from "@triport/sdk";


// Begin the OAuth flow; the callback completes it and sets the session cookie.
window.location.assign(authUrls.googleStart());

Python (triport-sdk)

# OAuth is an interactive, browser-only flow. There is no server-side
# equivalent; direct the user's browser to the start URL:
start_url = "https://api.triport.io/v1/auth/google/start"
print(f"Open this URL to sign in with Google: {start_url}")

Notes

  • Do not call directly. This is a redirect target for the browser. The session is established only when the cookies set here are stored by the browser.
  • After landing on /app/chains (or your configured post-login URL), the browser holds a valid nl_session cookie. Use it for authenticated console calls such as GET /v1/auth/me; include the nl_csrf value as the X-CSRF-Token header on mutating requests.
  • The state and PKCE verifier cookies are scoped to /v1/auth/google/ and are always cleared by the time this endpoint returns.
  • Related: GET /v1/auth/google/start, GET /v1/auth/me, POST /v1/auth/logout.