---
title: "Exchange a PKCE authorization code, poll a device code, or rotate a CLI refresh token"
method: POST
path: "/v1/auth/token"
tags: ["Authentication"]
---

# Exchange a PKCE authorization code, poll a device code, or rotate a CLI refresh token

`POST /v1/auth/token`

## Request

- Base URL: `https://api.masko.ai`
- URL: `https://api.masko.ai/v1/auth/token`
- Auth: none required

No bearer required. For authorization_code, send code, exact redirect_uri, and the original code_verifier; S256 must match the approved challenge. Codes expire after 120 seconds and are single-use. For device grants: authorization_pending: continue polling; slow_down: add 5 seconds to every subsequent interval; access_denied, expired_token, invalid_grant: stop. Access tokens last 900 seconds. Refresh tokens rotate once per use; reuse revokes the session. Serialize refreshes and save the returned pair atomically. Sessions expire after 90 days. Never log tokens.

## Request body

- union
  - object
    - `client_id` 'masko-cli', required
    - `grant_type` 'authorization_code', required
    - `code` string, required
    - `redirect_uri` string, uri, required
    - `code_verifier` string, required
  - object
    - `client_id` 'masko-cli', required
    - `grant_type` 'urn:ietf:params:oauth:grant-type:device_code', required
    - `device_code` string, required
  - object
    - `client_id` 'masko-cli', required
    - `grant_type` 'refresh_token', required
    - `refresh_token` string, required

## Response `200`

Success. Cache-Control: no-store.

- object
  - `data` object, required
    - `access_token` string, required
    - `refresh_token` string, required
    - `token_type` 'Bearer', required
    - `expires_in` number, required
    - `session_id` string, uuid, required
    - `session_expires_at` string, required

## Other responses

- `400`: Validation or device-grant state error.
- `429`: Rate limited.
- `503`: Authentication service unavailable.

---

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