> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.givechariot.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.givechariot.com/_mcp/server.

# Verify Authorization Token

POST https://api.givechariot.com/v1/authorization_tokens/verify
Content-Type: application/json

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.

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

Reference: https://docs.givechariot.com/api/authorization-tokens/verify

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Servers

- `https://api.givechariot.com` (Production, default)
- `https://sandboxapi.givechariot.com` (Sandbox)

## Request

### Body (application/json)

This endpoint expects an object.

- `code` (string, required) — The token's secret code value as provided by the donor. Verification is case-insensitive and tolerant of whitespace and dashes.
- `external_id` (string, optional) — 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

### 200

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

- `id` (string, required) — The unique identifier for this object.
- `status` (enum, required) — The status of a [Donor Account](/api/donor-accounts). * `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: `pending`, `approved`, `rejected`
- `donor` (DonorAccountDonor, required) — The donor's identity and profile information.
- `created_at` (datetime, required) — Time when this object was created. Expressed in RFC 3339 format.
- `updated_at` (datetime, required) — Time when this object was last updated. Expressed in RFC 3339 format.
- `external_id` (string, optional, nullable) — The DAF's internal identifier for this Donor Account. Can be set on creation or via [Update Donor Account](/api/donor-accounts/update) to link the DAFpay Donor Account to the donor's record in the DAF's own systems.
- `approval` (DonorAccountApproval, optional, nullable) — Details about the approval decision. Present when `status` is `approved`; otherwise `null`.
- `rejection` (DonorAccountRejection, optional, nullable) — Details about the rejection decision. Present when `status` is `rejected`; otherwise `null`.
- `disabled` (boolean, optional, default: false) — Whether this Donor Account is currently disabled. A disabled Donor Account remains `approved` but cannot submit new Grant Requests — call [Enable Donor Account](/api/donor-accounts/enable) to re-enable it. Disabling is only available for accounts in `approved` status.
- `metadata` (map from string to string, optional) — A map of arbitrary string keys and values to store information about the object.

## Errors

### 400 Bad Request Error

The request is invalid or contains invalid parameters

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 401 Unauthorized Error

Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 403 Forbidden Error

Access denied

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 404 Not Found Error

Resource Not Found

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 409 Conflict Error

Resource Conflicts

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 410 Gone Error

Resource Gone or Expired

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

### 500 Internal Server Error

Internal Server Error

- `type` (string, required) — A URI reference identifying the problem type.
- `title` (string, required) — A short, human-readable summary of the problem type.
- `status` (integer, required) — The HTTP status code for this error.
- `detail` (string, required) — A human-readable explanation specific to this occurrence.

## Types

### DonorAccountDonor

The donor's identity and profile information.

- `email` (string, required) — The donor's email. This is the donor's verified identifier — DAFpay verifies ownership via an email verification flow before a Donor Account is created.
- `first_name` (string, optional, nullable) — The donor's first name as captured during DAFpay profile setup. May be null for Donor Accounts created via [Create Donor Account](/api/donor-accounts/create) before the donor has authenticated.
- `last_name` (string, optional, nullable) — The donor's last name as captured during DAFpay profile setup. May be null for Donor Accounts created via [Create Donor Account](/api/donor-accounts/create) before the donor has authenticated.
- `phone` (string, optional, nullable) — The donor's phone number as captured during DAFpay profile setup. DAFpay does not currently verify ownership of the phone number. Treat this field as donor-asserted information.

### DonorAccountApproval

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

- `approved_at` (datetime, optional) — Time when the Donor Account was approved. Expressed in RFC 3339 format.
- `approved_by` (string, optional) — Identifier of the actor that approved this Donor Account. For DAF-initiated approvals, this is the DAF's API key principal. For automatic approvals via token verification, this is `system:authorization_token`.

### DonorAccountRejection

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

- `rejected_at` (datetime, optional) — Time when the Donor Account was rejected. Expressed in RFC 3339 format.
- `rejected_by` (string, optional) — Identifier of the actor that rejected this Donor Account. For DAF-initiated rejections, this is the DAF's API key principal.
- `rejection_reason` (string, optional) — A human-readable reason provided by the DAF when rejecting the Donor Account.

## Examples

**Request**

```json
{
  "code": "DAFP-7K3X-9M4Q"
}
```

**Response**

```json
{
  "id": "donor_account_01jpjenf5q6cawy43yxfcrxhct",
  "status": "approved",
  "donor": {
    "email": "warrenBuffet@example.com",
    "first_name": "Warren",
    "last_name": "Buffet",
    "phone": "+12125550100"
  },
  "created_at": "2026-04-01T12:00:00Z",
  "updated_at": "2026-04-02T18:30:00Z",
  "external_id": "ACME-DAF-DONOR-1042",
  "approval": {
    "approved_at": "2026-04-02T18:30:00Z",
    "approved_by": "daf:fid_01jpjenf5q6cawy43yxfcrxhct"
  },
  "rejection": null,
  "disabled": false
}
```