Sign in

v39

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-017897360.9 KB
Authorization Tokens

Verify Authorization Token

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, 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>
post/v1/authorization_tokens/verify

Request body

codestring required

The token's secret code value as provided by the donor. Verification is case-insensitive and tolerant of whitespace and dashes.

external_idstring

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.

Example request

{
  "code": "DAFP-7K3X-9M4Q",
  "external_id": "ACME-DAF-DONOR-1042"
}

Response

The token was successfully verified and the Donor Account was approved.

idstring required

The unique identifier for this object.

status'pending' | 'approved' | 'rejected' required

The status of a Donor Account.

  • 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.
external_idstring nullable

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.

disabledboolean

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.

created_atstring date-time required

Time when this object was created. Expressed in RFC 3339 format.

updated_atstring date-time required

Time when this object was last updated. Expressed in RFC 3339 format.

metadataobject

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

Example response

{
  "id": "donor_account_01jpjenf5q6cawy43yxfcrxhct",
  "status": "pending",
  "donor": {
    "email": "warrenBuffet@example.com",
    "first_name": "Warren",
    "last_name": "Buffet",
    "phone": "+12125550100"
  },
  "external_id": "ACME-DAF-DONOR-1042",
  "approval": {
    "approved_at": "2026-04-02T18:30:00Z",
    "approved_by": "daf:fid_01jpjenf5q6cawy43yxfcrxhct"
  },
  "rejection": {
    "rejected_at": "2026-04-02T18:30:00Z",
    "rejected_by": "daf:fid_01jpjenf5q6cawy43yxfcrxhct",
    "rejection_reason": "Donor could not be located in our records."
  },
  "created_at": "2026-04-01T12:00:00Z",
  "updated_at": "2026-04-02T18:30:00Z"
}