---
title: "Issue a short-lived elevated-permission token after password re-entry"
method: POST
path: "/v1/auth/step-up"
tags: ["Auth"]
---

# Issue a short-lived elevated-permission token after password re-entry

`POST /v1/auth/step-up`

## Request

- Base URL: `https://api.honkio.ca`
- URL: `https://api.honkio.ca/v1/auth/step-up`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Send the returned token as X-Step-Up-Token on the one request it is for: it is honoured once, expires after 5 minutes, and only works with the API key that requested it. `compliance:d` allows a right-to-erasure call. `api_keys:elevate` allows creating or rotating a key with permissions beyond the calling key's.

## Request body

- object
  - `password` string, required
  - `scope` 'compliance:d' | 'api_keys:elevate', required

## Response `200`

A single-use token for the X-Step-Up-Token header, valid for 5 minutes with the key that requested it.

- object: A single-use token for the X-Step-Up-Token header, valid for 5 minutes with the key that requested it.
  - `token` string, required
  - `scope` 'compliance:d' | 'api_keys:elevate', required
  - `expires_at` string, date-time, required

## Other responses

- `401`: UNAUTHORIZED: missing or invalid API key, or the password is wrong.
- `402`: The account has no balance, or a LIVE key was used before the first top-up.
- `403`: The API key lacks the permission this operation requires, or the account is suspended or closed.
- `422`: VALIDATION_ERROR: the request failed validation; details names the fields.
- `429`: RATE_LIMITED: 10 attempts per 15 minutes from one address, 20 wrong passwords per 15 minutes for one account, or the account-wide 100 requests per second.
- `500`: Unexpected server error.

---

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