---
title: "Inspect Setup Token"
method: POST
path: "/api/v1/auth/setup-token/inspect"
tags: ["auth"]
---

# Inspect Setup Token

`POST /api/v1/auth/setup-token/inspect`

Report what an account-setup token is worth, without consuming it.

Rate Limited: 20 requests per minute per IP address — headroom for a mail
gateway's link scanner plus the recipient's own page loads.

Does not require authentication; the token is the credential. Reading a
token must never consume it: Microsoft Defender Safe Links fetches every
URL in inbound mail before delivering it, so a consume-on-read token is
spent by a scanner before the recipient ever opens the message.

## Request body

- SetupTokenRequest — Request model for inspecting an account-setup token. The token rides in the body, never the path or query: every request's URL is recorded by the logging middleware, Logfire's FastAPI instrumentation, and Cloud Run's access log, so a token in the URL would be persisted in plaintext telemetry — the exact exposure hashing it in the database prevents.
  - `token` string, required

## Response `200`

Successful Response

- SetupTokenStatusResponse — Non-consuming check of an account-setup token. ``email`` is present only when ``status`` is ``valid`` — an invalid token must not reveal which account it belonged to.
  - `status` 'valid' | 'expired' | 'used' | 'unknown', required
  - `email` string, nullable

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/maia-analytics/apis/maia-api.md) · [All operations](https://skmtc.net/maia-analytics/apis/maia-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/maia-analytics/maia-api/revisions/ac8a0a8837e3/schema)