---
title: "Email a sign-in code"
method: POST
path: "/hd/desks/{desk_id}/auth/pin/start"
tags: ["hd"]
---

# Email a sign-in code

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

## Request

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

Start an emailed-code sign-in. The answer is the same for every address, known to the desk or not, and in every sign-in mode: a desk whose customers sign in with Secure Identity answers it and sends nothing. The code is sent from the desk's own mail domain and is good for 10 minutes and 5 attempts.

## Path parameters

- `desk_id` string, required

## Headers

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

## Request body

- object
  - `email` string, email, required: The address to send the code to.

## Response `202`

The challenge to verify the code against.

- object
  - `data` HelpDeskPinChallenge, required: A started emailed-code sign-in: the same shape whatever the address and the desk's sign-in mode.
    - `challenge_id` string, required: Names the challenge at verify.
    - `expires_at` integer, required: Epoch seconds the code expires at.
    - `binding_secret` string, required: Held in memory by the page that started the sign-in and sent back with the code: a verify from a page that does not hold it is refused. Answered once, never stored as given.
  - `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 `email` is missing or is no deliverable address. CLIENT_HEADER_REQUIRED — see above.
- `429`: RATE_LIMIT_EXCEEDED — this client address has spent its reads at the desk for the minute, it or its network has started too many sign-ins at the desk this hour, this address has been sent too many codes this quarter hour or day, or the desk has sent its codes for the hour. EMAIL_ACCOUNT_RATE_LIMIT — the organization has sent all the email it may send 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. EMAIL_SETUP_BUSY — another request is setting up the organization's email (`Retry-After` carries 5 seconds), or email setup is busy right now; repeat the request in a moment. INTERNAL_ERROR — no code was sent: the organization's email volume could not be counted (try again), or this deployment cannot send the help desk's email. 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/pin/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)