---
title: "Create Authorization Token"
method: POST
path: "/v1/donor_accounts/{id}/authorization_tokens"
tags: ["Authorization Tokens"]
---

# Create Authorization Token

`POST /v1/donor_accounts/{id}/authorization_tokens`

Create a single-use Authorization Token bound to a Donor Account.

Authorization Tokens are the binding credential used to verify a donor's identity between DAFpay and the DAF.
They are used in two distinct flows:

- **DAF-Initiated Setup**: The DAF creates a Donor Account and then creates an Authorization Token. The DAF surfaces the token's `code` to the donor via their portal. The donor enters the `code` into DAFpay during profile setup, automatically approving the Donor Account.
- **Donor-Initiated Verification**: After a donor submits a Grant Request, DAFpay automatically issues an Authorization Token and emails the `code` to the donor. The donor provides the `code` to the DAF (e.g. via a portal form or phone call). The DAF then calls [Verify Authorization Token](/api/authorization-tokens/verify) with the `code` to verify and approve the linked Donor Account.

Tokens expire **30 days** after creation by default. Override the lifetime by passing `expires_in` (seconds) on the request body — supported range is 60 seconds to 90 days. Once a token expires it transitions to `expired` and can no longer be verified; create a new token to issue a fresh code.

<Warning>
The token's `code` value is **only returned once** in this response. Treat it as a credential — store it securely and never log it. If the code is lost before being verified, [revoke](/api/authorization-tokens/revoke) the token and create a new one.
</Warning>

## Path parameters

- `id` string, required

## Request body

- object
  - `expires_in` integer — The number of seconds the token is valid for. Defaults to 30 days. Must be between 60 (1 minute) and 7,776,000 (90 days).
  - `metadata` object — A map of arbitrary string keys and values to store information about the object.

## Response `201`

Created

- DonorAuthorizationToken — A Donor Authorization Token is a single-use binding credential that ties a [Donor Account](/api/donor-accounts) to a verified identity exchange between DAFpay and the DAF. Tokens have two creation paths: - **DAF-Initiated Setup**: The DAF creates a Donor Account and then a token, surfaces the token's `code` to the donor via their portal, and the donor enters the `code` into DAFpay to approve their account. - **Donor-Initiated Verification**: After a donor submits a Grant Request without an approved Donor Account, DAFpay automatically creates a token and emails the `code` to the donor. The DAF later receives the `code` from the donor and calls [Verify Authorization Token](/api/authorization-tokens/verify) to approve the linked Donor Account. Tokens are single-use: once verified, the token's status becomes `verified` and the `code` cannot be used again.
  - `id` string, required — The unique identifier for this object.
  - `donor_account_id` string, required — The ID of the [Donor Account](/api/donor-accounts) this token is bound to.
  - `status` 'pending' | 'verified' | 'revoked' | 'expired', required — The status of a [Donor Authorization Token](/api/authorization-tokens). * `pending`: The token has been issued but not yet verified. * `verified`: The token has been verified and can no longer be used. * `revoked`: The token was explicitly revoked before being verified. * `expired`: The token's `expires_at` has passed and it can no longer be verified.
  - `code` string — The token's secret code value. <Warning> The `code` is **only returned in the response of [Create Authorization Token](/api/authorization-tokens/create)**. It is omitted from all other responses (Get, List). If the code is lost, [revoke](/api/authorization-tokens/revoke) the token and create a new one. </Warning> The format is a 12-character alphanumeric string designed to be easy for donors to read aloud or copy. Codes are not case-sensitive when verified.
  - `created_at` string, date-time, required — Time when the token was issued. Expressed in RFC 3339 format.
  - `expires_at` string, date-time, required — Time at which this token will expire and can no longer be verified. Defaults to 30 days after creation; configurable via the `expires_in` parameter on [Create Authorization Token](/api/authorization-tokens/create).
  - `verified_at` string, date-time — Time at which the token was verified. Only set when `status` is `verified`.
  - `revoked_at` string, date-time — Time at which the token was revoked. Only set when `status` is `revoked`.
  - `metadata` object — A map of arbitrary string keys and values to store information about the object.

## Other responses

- `400` — The request is invalid or contains invalid parameters
- `401` — Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.
- `403` — Access denied
- `404` — Resource Not Found
- `500` — Internal Server Error

---

[API](https://skmtc.net/chariot-giving/apis/specs.md) · [All operations](https://skmtc.net/chariot-giving/apis/specs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/chariot-giving/specs/revisions/8446023e02fb/schema)