Create Authorization Token

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 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.

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 the token and create a new one.

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>

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

idstringRequired

The unique id of the Donor Account

Request

The request to create a new Authorization Token bound to a Donor Account. All fields are optional — an empty body produces a token with default settings.

expires_inintegerOptional

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).

metadatamap from strings to stringsOptional

A map of arbitrary string keys and values to store information about the object.

Response

Created

idstringRead-only

The unique identifier for this object.

donor_account_idstringRead-only

The ID of the Donor Account this token is bound to.

statusenum

The status of a Donor Authorization Token.

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.

Allowed values:

created_atstringRead-onlyformat: "date-time"

Time when the token was issued. Expressed in RFC 3339 format.

expires_atstringRead-onlyformat: "date-time"

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.

codestringRead-only

The token’s secret code value.

The code is only returned in the response of Create Authorization Token. It is omitted from all other responses (Get, List). If the code is lost, revoke the token and create a new one.

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.

verified_atstringRead-onlyformat: "date-time"

Time at which the token was verified. Only set when status is verified.

revoked_atstringRead-onlyformat: "date-time"

Time at which the token was revoked. Only set when status is revoked.

metadatamap from strings to strings

A map of arbitrary string keys and values to store information about the object.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error

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 with the code to verify and approve the linked Donor Account.

$	curl -X POST https://api.givechariot.com/v1/donor_accounts/donor_account_01jpjenf5q6cawy43yxfcrxhct/authorization_tokens \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{}'

1	{
2	"id": "auth_token_01jpjenf5q6cawy43yxfcrxhct",
3	"donor_account_id": "donor_account_01jpjenf5q6cawy43yxfcrxhct",
4	"status": "pending",
5	"created_at": "2026-04-01T12:00:00Z",
6	"expires_at": "2026-05-01T12:00:00Z",
7	"code": "DAFP-7K3X-9M4Q"
8	}