Skip to navigation
Donor AccountsAuthorization 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.

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.

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 headers

X-Request-IdstringOptional
The unique identifier for the request

Response

The token was successfully verified and the Donor Account was approved.
idstringRead-only
The unique identifier for this object.
statusenum

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.
Allowed values:
donorobject
The donor's identity and profile information.
created_atdatetimeRead-only
Time when this object was created. Expressed in RFC 3339 format.
updated_atdatetimeRead-only
Time when this object was last updated. Expressed in RFC 3339 format.
external_idstring or nullOptional

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 nullOptionalRead-only

Details about the approval decision. Present when status is approved; otherwise null.

rejectionobject or nullOptionalRead-only

Details about the rejection decision. Present when status is rejected; otherwise null.

disabledbooleanOptionalRead-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 stringsOptional
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
409
Conflict Error
410
Gone Error
500
Internal Server Error