POST /v1/console/oauth/github/callback

Call	POST /v1/console/oauth/github/callback
Price	free
Scope	none (public endpoint)
Operation id	githubOauthCallback

What it does

Complete GitHub sign-in: Verdict checks state against the browser’s state cookie, exchanges code with GitHub and signs in the existing user whose verified email matches the GitHub account’s verified primary email (the GitHub identity is linked on first use). GitHub sign-in does not create accounts: sign up with POST /v1/signup first. Sets the verdict_session cookie. No key or session needed.

Example request

Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.

Request

curl -X POST 'https://api.askverdict.io/v1/console/oauth/github/callback' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "gh-code-example",
  "state": "sssssssssssssssssssssssssssssssssssssssssss"
}'

Example response

200: Signed in; the cookie is set.

200 response

{
  "user": {
    "id": "usr_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
    "email": "[email protected]",
    "totp_enabled": false
  },
  "orgs": [
    {
      "id": "org_01JC3Z4Y8R9K2M5N7P1Q3S5T7V",
      "name": "Northwind Ops",
      "slug": "northwind-ops",
      "role": "owner",
      "created_at": "2026-11-01T09:00:00Z"
    }
  ],
  "mfa_verified": false,
  "idle_expires_at": "2026-11-14T14:00:00Z"
}

Parameters

Name	In	Type	Required	Description
idempotency-key	header	string (uuid)	yes	A UUID you generate per logical request. Required on every POST. Repeating it within 24 hours returns the stored response and bills nothing; reusing it with a different body returns 409 idempotency_conflict.

Request body

Schema GithubOauthCallbackRequest. What GitHub returned.

Field	Type	Required	Description
code	string	yes	The code GitHub returned.
state	string	yes	The state GitHub returned.

Response fields (200)

Schema ConsoleSession.

Field	Type	Required	Description
user	ConsoleUser	yes	A console user.
user.id	string	yes	User id.
user.email	string (email)	yes	The user’s verified email.
user.totp_enabled	boolean	yes	Whether TOTP is turned on.
orgs	array of ConsoleOrg	yes	Organizations the user belongs to.
orgs[].id	string	yes	Organization id.
orgs[].name	string	yes	Organization name.
orgs[].slug	string	yes	URL-safe organization slug.
orgs[].role	enum: “owner”, “admin”, “developer”, “billing”, “read_only”	yes	The user’s role in this organization.
orgs[].created_at	string (date-time)	yes	When the organization was created.
mfa_verified	boolean	yes	Whether this session has passed TOTP. When the user has TOTP on and this is false, org actions answer 401 until POST /v1/console/totp/verify succeeds.
idle_expires_at	string (date-time)	yes	When the session expires if it is not used again (7 days after last use).

Errors

Errors are RFC 9457 problem details and are never billed. Branch on type. See Errors.

Status	Meaning
400	Invalid request: malformed JSON, an unknown field, a failed constraint or a size limit (invalid_request).
401	Missing, malformed, revoked or expired API key, or a bad webhook signature (unauthorized).
429	Rate limited (rate_limited). Wait Retry-After seconds.
500	Unexpected server error (internal). Not billed; retry with the same Idempotency-Key.

Try it

Open the interactive reference to send this request from the browser. The full document is at /openapi.json.