---
title: "OIDC callback: verify the ID token, find-or-create the user, issue a session"
method: GET
path: "/v1/auth/callback"
tags: ["auth"]
---

# OIDC callback: verify the ID token, find-or-create the user, issue a session

`GET /v1/auth/callback`

## Request

- Base URL: `https://api.wavehouse.cloud`
- URL: `https://api.wavehouse.cloud/v1/auth/callback`
- Auth: none declared

A browser (an `Accept` naming text/html) is always redirected: to the console when signed in, to a fresh sign-in at most once, else to the console's sign-in error page with a `reason`; a retry and that page keep the sign-in's original destination. Any other caller gets the failure as a problem.

## Query parameters

- `code` string
- `state` string
- `error` string: Set by the provider when the user denies consent or an error occurs

## Cookies

- `whc_oidc_tx` string
- `whc_cb_retry` string
- `whc_last_org` string

## Other responses

- `302`: Found
- `401`: Sign-in failed.
- `429`: Rate limited, per client IP, API key or org; a client IP is also refused on every route for a while after repeated authentication failures. A limited operation carries RateLimit-Policy and RateLimit on every response; wait Retry-After seconds before retrying.
- `503`: The identity provider is unreachable, or new sign-ups are paused and this is a first sign-in; sign in again after Retry-After seconds.

---

[API](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api.md) · [All operations](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wavehouse/apis/wavehouse-cloud-api/revisions/adea029bf505?raw)