---
title: "Trade a one-time sign-in token for a web API key"
method: POST
path: "/v1/auth/exchange"
tags: ["sign-in"]
---

# Trade a one-time sign-in token for a web API key

`POST /v1/auth/exchange`

## Request

- Base URL: `https://api.hookdetector.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.hookdetector.com/v1/auth/exchange`
- Auth: none declared

The web calls this with the token from /signin/callback#t=... after Google sign-in.
The token works once, for 60 seconds. The answer is a new API key named "web sign-in"
with every scope and a 30-day expiry, the person (`user`) and where to go next
(`return_to`). An account keeps at most 3 web keys: the oldest is revoked. 409
key_limit_reached when the account already holds the most keys it can and none of
them is a web key. Free. Called from the web's own origin, the key is also set in the
session cookie, which the web then uses instead (FAILURE_MODES.md WS1).

## Request body

- ExchangeIn
  - `token` string, required: the t value of the /signin/callback#t=... fragment

## Response `200`

Successful Response

- ExchangeOut
  - `api_key` string, required: the web key; shown once, send it as Bearer
  - `key_id` string, required
  - `prefix` string, required
  - `created_at` string, required
  - `expires_at` string, required: 30 days from now
  - `account_id` string, required
  - `return_to` string, required: the same-site path to go to next
  - `user` SignedInUser, required
    - `email` string, required
    - `name` string, nullable, required
    - `avatar_url` string, nullable, required
    - `is_admin` boolean, required

## Other responses

- `401`: the token is unknown, used or older than 60 seconds (invalid_exchange_token)
- `409`: conflict with the account's state
- `413`: request body over the size cap
- `422`: invalid input
- `500`: our fault; names the request id

---

[API](https://skmtc.dev/hookdetector/apis/hook-detector.md) · [All operations](https://skmtc.dev/hookdetector/apis/hook-detector/llms.txt) · [OpenAPI document](https://skmtc.dev/hookdetector/apis/hook-detector/revisions/b136a2804d2b?raw)