Authorization header using the Bearer scheme. Every request to a Raise endpoint requires this header — there are no public, unauthenticated endpoints on the API.
This page covers the token format, the header structure, how to obtain a token, and best practices for storing and rotating credentials in a partner integration.
The authentication scheme
The Raise spec declares a single security scheme namedBearer:
| Property | Value |
|---|---|
| Type | API key (passed in a header) |
| Header name | Authorization |
| Format | Bearer {token} |
| Token type | JWT (JSON Web Token) |
401 Unauthorized response. See Error Handling for the error envelope.
Making an authenticated request
The header is the same regardless of endpoint or HTTP method:Authorization header sits alongside the standard Content-Type: application/json:
cURL
Obtaining a token
Raise tokens are issued at the organization level — one Raise account (one nonprofit organization) produces tokens that the integration uses to read and write that organization’s data. Partner integrations serving multiple customers hold one token per customer. The exact token-issuance flow happens inside the Raise application (not via API). The customer’s Raise administrator generates the token in their account settings and provides it to the partner integration through whatever onboarding flow the partner has built — typically a settings page in the partner’s product where the customer pastes the token.Confirm the exact in-app path the customer’s Raise administrator takes to generate a token before publishing integration onboarding documentation. The Raise admin UI structure is outside the API surface and may evolve.
Per-customer tokens
In a multi-tenant partner integration, each customer’s Raise organization has its own token. The integration holds N tokens for N customers and selects the right one based on which customer’s data it’s reading or writing. Never share a token across customers, hardcode tokens in source, or use a partner-owned token to read multiple customers’ data. The token’s scope is the issuing organization; cross-organization access is not the intended use. See Security and Credential Management for the storage patterns that support per-customer credentials cleanly.Authentication errors
A request that fails authentication receives401 Unauthorized. The response body contains an error message identifying the cause:
| Likely cause | What to check |
|---|---|
Missing Authorization header | Confirm the header is present on every request, not just the first. |
| Wrong header name or format | Must be exactly Authorization: Bearer {token} — common mistakes include Authentication, Token, or omitting the Bearer prefix. |
| Token expired | JWTs typically have an expiration claim. If the token has expired, generate a new one. |
| Token revoked | The customer may have revoked the token from the Raise admin UI. Confirm with the customer before retrying. |
| Wrong token for the request’s organization | If the integration is multi-tenant, verify the right token was selected for the customer being acted on. |
| Token tampered with | If the JWT signature doesn’t validate, the token has been modified. Generate a fresh one. |
401 after fixing the header is almost always a token problem on the credential side, not a request problem. Do not retry blindly — the next call will fail the same way.
See Error Recovery Patterns: classifying errors for the broader pattern of classifying authentication failures as persistent-recoverable rather than transient.
Storing tokens
Treat Raise tokens like any other production secret. The acceptable storage:| Option | Use |
|---|---|
| Cloud-provider secrets manager (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault) | The default for most cloud deployments |
| Self-hosted secrets manager (Vault, Bitwarden Secrets Manager) | For environments not running in a cloud provider |
| Encrypted database column with a managed encryption key | Acceptable when secrets manager isn’t available; requires careful key rotation |
- Environment variables in deployment manifests (visible to anyone with deploy access)
.envfiles in source control (visible in git history forever)- Plaintext database columns
- Hardcoded in source
Rotating tokens
Raise tokens should be rotated periodically. The cadence depends on the integration’s threat model — typical recommendations are every 90 days for high-sensitivity integrations, every 6–12 months for lower-sensitivity ones. The rotation flow:Generate a new token in the Raise admin UI
The customer’s Raise administrator generates a fresh token. The old token remains valid until explicitly revoked.
Add the new token alongside the existing one
Store the new token in the secrets manager under a
pending marker.Cut over reads to the new token
Integration workers start using the new token. The old token remains accessible to handle in-flight requests.
Validate
Confirm a successful API call with the new token. Check for any unexpected
401 responses from workers that didn’t see the cutover.What’s distinct about Raise auth
For partners coming from CRM+, two things to keep in mind:- Different host means different token. A CRM+ token doesn’t work against Raise, and vice versa. Each product issues its own tokens; the integration holds both for customers using both products.
- No documented refresh flow. Raise tokens are long-lived JWTs that the customer generates and provides to the integration. The current spec does not document a refresh-token or token-exchange flow. If a customer’s token expires or is revoked, the only path forward is for the customer’s administrator to issue a new one and the partner to update their stored credential.
Where to go next
Base URLs and Environments
The Raise host and environment-selection details that pair with authentication.
Your First API Call
A walkthrough of a successful authenticated request and response.
Error Handling
What to expect from
401 and other error responses.Security and Credential Management
The deep-dive on per-customer credential storage and rotation.