---
title: "Consume a one-time auth handoff and mint a Eurobase session"
method: POST
path: "/auth/provider-handoffs/exchange"
---

# Consume a one-time auth handoff and mint a Eurobase session

`POST /auth/provider-handoffs/exchange`

## Request

- Base URL: `https://api.eurobase.dev`
- URL: `https://api.eurobase.dev/auth/provider-handoffs/exchange`
- Auth: none declared

Creates or links a PostgreSQL-clocked 35-day browser session and returns the authenticated identity. Browser session state is established by Set-Cookie, not a JSON bearer token. A login handoff is accepted only with the __Host-eurobase_login_binding cookie of the browser that started the login.

## Response `200`

Eurobase session minted

- AuthProviderExchangeResponse
  - `user` AuthUser, required
    - `id` string, required
    - `email` string, required
    - `status` string, nullable
    - `deleteRequestedAt` string, date-time, nullable
    - `deletionState` 'billing_pending' | 'cleanup_pending' | 'null', nullable
    - `emailVerifiedAt` string, date-time, nullable
    - `emailVerified` boolean, required
    - `authAccessState` 'verified' | 'email_verification_required', required
    - `avatarUrl` string, nullable, required: Profile picture of the most recently used linked Google or GitHub sign-in that has one.
    - `createdAt` string, date-time, required
  - `authAccessState` 'verified' | 'email_verification_required', required
  - `emailVerification` object, required
    - `required` boolean, required
    - `verified` boolean, required
    - `sent` boolean, required
  - `capabilities` SessionCapabilities, required
    - `operator` boolean, required
    - `ownerOperator` boolean, required
  - `clientIp` string, nullable, required
  - `provider` 'google' | 'github', required
  - `returnTo` string, required

## Other responses

- `400`: New linked identity email is malformed, disposable or unroutable (unverified provider mail requires DNS)
- `401`: Handoff invalid, expired or reused (auth-provider-handoff-invalid), login started in another browser (auth-provider-browser-mismatch), or link finished outside its initiating session (auth-provider-handoff-session-mismatch); no cookie is set
- `415`: Request body is not application/json
- `503`: Unverified new linked email DNS is temporarily unavailable

---

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