---
title: "Begin a Secure Identity sign-in"
method: POST
path: "/hd/desks/{desk_id}/auth/identity/start"
tags: ["hd"]
---

# Begin a Secure Identity sign-in

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

## Request

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

The authorize URL of the desk organization's own Secure Identity for the desk's sign-in client, to send the browser to, and the binding the tab keeps until the sign-in returns. The sign-in returns to `{origin}/auth/callback`, where the portal completes it with that binding; it completes for no other tab. Only a desk whose customers sign in with Secure Identity answers it.

## Path parameters

- `desk_id` string, required

## Headers

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

## Request body

- object
  - `origin` string, required: The portal origin the sign-in starts on: one of the desk's own addresses.
  - `return_to` string, required: The path on that origin to return to after sign-in.

## Response `200`

Where to send the browser, and what to send back with the code.

- object
  - `data` object, required
    - `authorize_url` string, uri, required
    - `binding` string, required: Kept by the tab that began the sign-in for the trip to the identity service and back (the portal keeps it in sessionStorage) and sent with the code to complete it: a completion without it is refused, and one with another sign-in's refuses and spends the round trip. Never part of the authorize URL.
  - `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, `origin` is not one of the desk's addresses, or `return_to` is not a path on it. CLIENT_HEADER_REQUIRED — see above.
- `429`: RATE_LIMIT_EXCEEDED — this client address has spent its reads at the desk for the minute, or it or its network has started too many sign-ins at the desk this hour. `Retry-After` carries the seconds until the budget reopens, and `details` carries `limit` and `resets_at`.
- `503`: HELP_DESK_UNAVAILABLE — the desk does not take customers right now, or its customers do not sign in with Secure Identity now (a desk that prefers it while the organization's Identity does not serve signs nobody in and alerts its admins). 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`: 12 info
  - the response property `error/details` became required for the status `400`
  - the response property `error/details` became required for the status `429`
  - the response property `error/details` became required for the status `503`
  - the response property `meta` became required for the status `400`
  - …8 more
- **2026-10-28** `56d7c265a77a`: 3 breaking
  - the response property `error/details` became nullable for the status `400`
  - 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/start/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)