Authentication

Infinite Giving uses the OAuth2 authorization code flow for API authentication. This guide covers how to obtain credentials and authenticate your API requests.

Getting your credentials

To access the Infinite Giving API, you'll need a client ID and client secret. You can request credentials from our team.

Platform partners must have an Infinite Giving organization account before kickoff. See Partnerships for what to provide (OAuth callback URL, webhook URL, logo, etc.) and what we configure for you.

Environments

Infinite Giving runs a sandbox environment for partner development and a production environment for live donations. Build and test against sandbox first; we move you to production once your integration is verified.

Credentials, organizations, and donations are not shared between environments. Your sandbox client ID and secret will not authenticate against production, and each environment needs its own registered OAuth callback URL and webhook destination URL. Webhooks are delivered from the environment the donation happened in.

The examples below use the production hosts — swap in the sandbox hosts while you are developing.

Authorization flow overview

Step 1: Redirect to authorization

Direct the user to the authorization endpoint with the required parameters.

https://auth.infinitegiving.com/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=YOUR_REQUIRED_SCOPES&
  state=RANDOM_STATE_VALUE

Step 2: Handle the callback

After the user authorizes your application, they'll be redirected to your redirect_uri with an authorization code.

https://yourapp.com/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_VALUE

Step 3: Exchange code for tokens

Exchange the authorization code for access and refresh tokens from your server.

Token request

curl -X POST https://auth.infinitegiving.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://yourapp.com/callback"

Token response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "ig_organizations": [{ "id": "01HZX...", "name": "Example Nonprofit" }]
}

Identifying the customer organization

Partner endpoints are scoped to a nonprofit's organization id (the :organization_id path parameter). ig_organizations tells you which, and is always a list so you can branch on its length:

• One entry — the common case. Use its id. This covers customers who signed up through your referral link and users who own a single organization.
• Several entries — the user owns more than one eligible organization and we will not guess which you meant. Prompt them to pick, then use that entry's id.
• Empty — the authorizing user owns no eligible organization (for example they are a non-owner member). Contact your Infinite Giving representative.

id is the organization's public id, the same value used in API paths, never an internal identifier. The field is returned on both the authorization_code and refresh_token grants, so persist the id against your own customer record rather than re-deriving it on every call.

Making authenticated requests

Include your access token in the Authorization header for all API requests.

curl https://api.infinitegiving.com/v1/organizations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Refreshing tokens

When an access token expires, use the refresh token to obtain a new one without requiring user interaction.

curl -X POST https://auth.infinitegiving.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Error responses

Invalid authorization code

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired or is invalid"
}

Authorization codes are single-use and expire after a short period. Restart the authorization flow if you receive this error.

Expired token

{
  "error": "invalid_token",
  "error_description": "The access token has expired"
}

Use your refresh token to obtain a new access token.

Invalid refresh token

{
  "error": "invalid_grant",
  "error_description": "The refresh token is invalid or has been revoked"
}

The user will need to re-authorize your application.

Best practices

Secure credential storage

• Store credentials in environment variables or a secrets manager
• Never commit credentials to version control
• Use different credentials for development and production

Token management

• Cache access tokens and reuse them until near expiration
• Securely store refresh tokens (they grant long-lived access)
• Handle token errors gracefully with retry logic

Request security

• HTTPS is required for redirect URIs
• Validate the state parameter on every callback
• Validate SSL certificates in production