---
title: "Exchange a signed login challenge for a session"
method: POST
path: "/auth/token"
tags: ["auth"]
---

# Exchange a signed login challenge for a session

`POST /auth/token`

## Request

- The document declares no server URL.
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/hevn-inc/apis/hevn-api/docs/auth/token/post.ts> (a function with typed inputs; its response is checked against the schema)

Exchange a signed, unexpired challenge for an access token and refresh token. A challenge is consumed once; replay, a different key or a different account is refused.

## Headers

- `device-id` string, nullable
- `user-agent` string, nullable

## Request body

- union
  - ChallengeTokenRequest
    - `challengeId` string, uuid, required: Single-use challenge identifier returned by POST /dapi/v1/auth/challenge.
    - `signature` string, required: Signature over the decoded payload returned for this challenge.
    - `publicKey` string, nullable: Registered P-256 public key; omit when the signature uniquely identifies the key.
  - ProofTokenRequest
    - `email` string, email, required: Email address of the account that owns the registered developer key.
    - `publicKey` string, required: Base64 DER SubjectPublicKeyInfo for the registered P-256 developer key.
    - `nonce` integer, required: Caller-generated single-use number included in the signed authentication proof.
    - `requestExpiry` integer, required: Unix time in milliseconds after which the signed request is refused.
    - `signature` string, required: Base64 DER ECDSA P-256/SHA-256 signature over the login proof message.

## Response `200`

Successful Response

- TokenResponse
  - `accessToken` string, required: Short-lived bearer token used to authorize API requests.
  - `refreshToken` string, required: Long-lived device-bound token used only at POST /dapi/v1/auth/refresh.
  - `expiresIn` integer, required: Number of seconds until the access token expires.
  - `userId` string, required: Account selected for the issued session.

## Other responses

- `422`: Request validation failed

## Changes

- **2026-11-12** `299a3aa6f521`: 1 warning, 2 info
  - added the new `verification_not_applicable` enum value to the `error/code` response property for the response status `422`
  - removed the `phone_required` enum value from the `error/code` response property for the response status `422`
  - removed the `rail_requirements_unmet` enum value from the `error/code` response property for the response status `422`
- **2026-10-23** `a02795de2d2b`: 9 warning, 5 info
  - deleted the `header` request parameter `x-api-key`
  - added the new `client_already_linked` enum value to the `error/code` response property for the response status `422`
  - added the new `kyb_documents_processing` enum value to the `error/code` response property for the response status `422`
  - added the new `link_code_expired` enum value to the `error/code` response property for the response status `422`
  - …10 more
- **2026-10-20** `19eb00e9f258`: 1 info
  - removed the `phone_in_use` enum value from the `error/code` response property for the response status `422`
- **2026-10-20** `bd6c9d69540e`: 1 warning
  - added the new `phone_in_use` enum value to the `error/code` response property for the response status `422`
- **2026-10-20** `19eb00e9f258`: 1 info
  - removed the `document_fields_missing` enum value from the `error/code` response property for the response status `422`

[Operation history](https://skmtc.dev/hevn-inc/apis/hevn-api/changes/auth/token/post.md)

---

[API](https://skmtc.dev/hevn-inc/apis/hevn-api.md) - [All operations](https://skmtc.dev/hevn-inc/apis/hevn-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hevn-inc/apis/hevn-api/revisions/299a3aa6f521?raw)