---
title: "Renew a Secure Identity session"
method: POST
path: "/hd/desks/{desk_id}/auth/identity/refresh"
tags: ["hd"]
---

# Renew a Secure Identity session

`POST /hd/desks/{desk_id}/auth/identity/refresh`

## Request

- Base URL: `https://api.sparkvault.com/v1`
- URL: `https://api.sparkvault.com/v1/hd/desks/{desk_id}/auth/identity/refresh`
- Auth: none required
- TypeScript: <https://skmtc.dev/sparkvault/apis/sparkvault-api/docs/hd/desks/:desk_id/auth/identity/refresh/post.ts> (a function with typed inputs; its response is checked against the schema)

Trade the refresh token for a new access token at the desk organization's Secure Identity. The refresh token is spent by its one use: the answer carries the next one. A renewal is answered only while the customer is not refused at the desk and the identity service's directory names the person the holder of the address their requests are under. A refusal answers no tokens, and the customer signs in again; when the desk refuses after the identity service rotated the pair (the customer is refused, or the person no longer holds that address), the session it rotated is revoked there first. A renewal that fails short of a refusal revokes nothing, so a prompt retry can still renew.

## Path parameters

- `desk_id` string, required

## Headers

- `X-SV-Client` 'help-desk-portal', required

## Request body

- object
  - `refresh_token` string, required

## Response `200`

The new tokens.

- object
  - `data` HelpDeskIdentityRenewal, required
    - `token` string, required: The new access token.
    - `expires_in` integer, required: Seconds until it expires.
    - `refresh_token` string, required: The refresh token to use next; the one presented is spent.
  - `meta` ResponseMeta: Envelope metadata present on every successful response.
    - `api_version` string
    - `request_id` string
    - `response_ms` integer
    - `timestamp` integer: Unix seconds.
    - `pools` object: Storage and bandwidth capacity snapshot for the account.
    - `billing` object
      - `past_due` boolean
    - `quota` object: This minute of the account request budget. Present on authenticated success responses that passed the throttle; absent otherwise.
      - `limit` integer
      - `used` integer
      - `remaining` integer
      - `resets_at` integer: Unix seconds.

## Other responses

- `400`: VALIDATION_ERROR — the body is no JSON object, or `refresh_token` is not a non-empty string of at most 8192 characters. CLIENT_HEADER_REQUIRED — see above.
- `401`: AUTHENTICATION_ERROR — the identity service refused the refresh token (spent, revoked, expired or its session ended), the person no longer holds the address their requests are under, or the desk's customers sign in with an emailed code now.
- `429`: RATE_LIMIT_EXCEEDED — this client address has spent its reads at the desk for the minute, or the identity service refused the renewal for its rate. `Retry-After` carries the seconds until the budget reopens, and `details` carries `limit` and `resets_at`. The identity service's own refusal carries only what it names.
- `503`: HELP_DESK_UNAVAILABLE — the desk does not take customers right now, prefers Secure Identity while it does not serve, or this customer is refused. INTERNAL_ERROR — the identity service did not answer, or answered no access token the desk accepts. BUDGET_UNAVAILABLE — a budget the request spends could not be counted, so the request was refused rather than let through uncounted; `Retry-After` carries the seconds to wait before trying again.

## Changes

- **2026-10-28** `a9a10e328ba5`: 16 info
  - the response property `error/details` became required for the status `400`
  - the response property `error/details` became required for the status `401`
  - the response property `error/details` became required for the status `429`
  - the response property `error/details` became required for the status `503`
  - …12 more
- **2026-10-28** `56d7c265a77a`: 4 breaking
  - the response property `error/details` became nullable for the status `400`
  - the response property `error/details` became nullable for the status `401`
  - the response property `error/details` became nullable for the status `429`
  - the response property `error/details` became nullable for the status `503`
- **2026-10-23** `ad4c62db5e08`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sparkvault/apis/sparkvault-api/changes/hd/desks/:desk_id/auth/identity/refresh/post.md)

---

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