For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Verify an Authorization Token by its `code` value.
This endpoint is used by DAFs in the **Donor-Initiated Verification** flow: when a donor presents the `code` they received from DAFpay (via email after submitting a Grant Request), the DAF calls this endpoint with the `code` to confirm the donor's identity.
On success:
- The Authorization Token transitions to `verified`.
- The linked Donor Account is automatically transitioned to `approved` if it is currently `pending`.
- The full Donor Account is returned (including the `id` you can use to call subsequent endpoints).
Codes are only valid until the token's `expires_at` — **30 days** after creation by default (configurable via `expires_in` on [Create Authorization Token](/api/authorization-tokens/create), 60 seconds to 90 days). After that point, the token's status becomes `expired` and verification will fail. If the donor's code has expired, prompt them to submit a new Grant Request — DAFpay will issue and email a fresh code automatically.
<Warning>
Error handling:
- If the `code` is unknown, expired, revoked, or already verified, the request will return status `404 Not Found` or `410 Gone` to avoid leaking information about valid codes. Expired codes are intentionally indistinguishable from other invalid codes in the response — surface a generic "code is invalid or has expired" message to the donor and ask them to request a new code.
- If the linked Donor Account has already been rejected, the request will return status `409 Conflict`.
- To prevent brute-force attacks, this endpoint enforces strict per-DAF rate limits. Repeated failures will return status `429 Too Many Requests`.
</Warning>
Authentication
AuthorizationBearer
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
The request to verify an Authorization Token by its code value.
codestringRequired
The token’s secret code value as provided by the donor. Verification is case-insensitive and tolerant of whitespace and dashes.
external_idstringOptional
The DAF’s internal identifier for this Donor Account. If provided, will be set on the Donor Account as part of the verification. Maximum length: 255 characters.
Response
The token was successfully verified and the Donor Account was approved.
pending: The Donor Account has been created but the DAF has not yet approved or rejected it.
approved: The DAF has verified the donor’s identity and Grants from this account can be processed.
rejected: The DAF has rejected the Donor Account. Grants from this account will not be processed.
Allowed values:
donorobject
The donor's identity and profile information.
created_atstringRead-onlyformat: "date-time"
Time when this object was created. Expressed in RFC 3339 format.
updated_atstringRead-onlyformat: "date-time"
Time when this object was last updated. Expressed in RFC 3339 format.
external_idstring or null
The DAF’s internal identifier for this Donor Account. Can be set on creation or via Update Donor Account to link the DAFpay Donor Account to the donor’s record in the DAF’s own systems.
approvalobject or nullRead-only
Details about the approval decision. Present when status is approved; otherwise null.
rejectionobject or nullRead-only
Details about the rejection decision. Present when status is rejected; otherwise null.
disabledbooleanRead-onlyDefaults to false
Whether this Donor Account is currently disabled. A disabled Donor Account remains approved but cannot submit new Grant Requests — call Enable Donor Account to re-enable it. Disabling is only available for accounts in approved status.
metadatamap from strings to strings
A map of arbitrary string keys and values to store information about the object.
This endpoint is used by DAFs in the Donor-Initiated Verification flow: when a donor presents the code they received from DAFpay (via email after submitting a Grant Request), the DAF calls this endpoint with the code to confirm the donor’s identity.
On success:
The Authorization Token transitions to verified.
The linked Donor Account is automatically transitioned to approved if it is currently pending.
The full Donor Account is returned (including the id you can use to call subsequent endpoints).
Codes are only valid until the token’s expires_at — 30 days after creation by default (configurable via expires_in on Create Authorization Token, 60 seconds to 90 days). After that point, the token’s status becomes expired and verification will fail. If the donor’s code has expired, prompt them to submit a new Grant Request — DAFpay will issue and email a fresh code automatically.
Error handling:
If the code is unknown, expired, revoked, or already verified, the request will return status 404 Not Found or 410 Gone to avoid leaking information about valid codes. Expired codes are intentionally indistinguishable from other invalid codes in the response — surface a generic “code is invalid or has expired” message to the donor and ask them to request a new code.
If the linked Donor Account has already been rejected, the request will return status 409 Conflict.
To prevent brute-force attacks, this endpoint enforces strict per-DAF rate limits. Repeated failures will return status 429 Too Many Requests.
