---
title: "Exchange a handoff code for credentials"
method: POST
path: "/agent_sessions"
tags: ["Agent sessions"]
---

# Exchange a handoff code for credentials

`POST /agent_sessions`

## Request

- Base URL: `https://www.happyscribe.com/api/v1`
- URL: `https://www.happyscribe.com/api/v1/agent_sessions`
- Auth: none required

Turns the code a user copied from the agent handoff page
(`https://www.happyscribe.com/app/agent_sessions/new`) into that user's personal
API key and a workspace the user can write to. No API key is needed for this
call: the code is the credential. Codes expire five minutes after the page
loads. See [auth.md](/auth.md) for the full agent flow.

## Request body

- object
  - `token` string, required: The code shown on the handoff page.

## Response `200`

The credentials the agent should use from now on.

- object
  - `api_key` string, required: The user's personal API key. Send it bare in the `Authorization` header.
  - `workspace_id` union, required: A workspace the user can write to, as a `wks_` id. This call has no key to pin, so send `Happyscribe-Version` with it; without the header the id is an integer. Either form works as input.
    - string
    - integer

## Other responses

- `401`: The code is invalid or expired (`invalid_code`). Ask the user to reload the handoff page for a fresh one.
- `429`: Rate limit reached (`rate_limited`). Wait `retry_in_seconds`, also sent as `Retry-After`, before retrying.

---

[API](https://skmtc.dev/happyscribe/apis/happyscribe-api.md) - [All operations](https://skmtc.dev/happyscribe/apis/happyscribe-api/llms.txt) - [OpenAPI document](https://skmtc.dev/happyscribe/apis/happyscribe-api/revisions/1281bd968c3d?raw)