Skip to main content
The Volunteer API authenticates with a single mechanism: a Bearer token in the HTTP Authorization header. The pattern is straightforward and follows IETF RFC 6750, but a few specifics about how Volunteer’s tokens are issued and managed matter for partner integrations. This page covers obtaining the token, using it on every request, storing it securely, rotating it, and handling auth failures.

​
At a glance

ConcernHow Volunteer handles it
Auth mechanismBearer token in Authorization header
Token formatJWT (per eyJhbGci... prefix in examples)
Token issuanceGenerated in the VOMO admin portal by the customer’s administrator
Token scopeA single VOMO organization
Token expirationNot documented in the spec
Token rotationManual — administrator regenerates and provides new token
RevocationDone in the admin portal

​
Obtaining a token

Volunteer tokens are issued by the customer (or their VOMO concierge) — not by the partner integration. The flow:
1

Confirm API access is enabled for the customer's VOMO account

API access is not on by default. The customer or partner contacts the customer’s VOMO concierge to enable it. Until enabled, no tokens can be generated.
2

The customer's VOMO administrator generates a token in the admin portal

Logged into the VOMO admin UI, the administrator navigates to the API access section and generates a new token. The token displays once; the administrator copies it.
3

The customer provides the token to the partner integration

Through whatever secure-handoff mechanism the partner has built into onboarding — typically a settings UI in the partner’s product where the customer pastes the token, transmitted over HTTPS.
4

The partner stores the token securely

In a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.). One token per customer; never share tokens across customers.
The exact UI path in the VOMO admin portal for token generation, and whether tokens can be named or scoped beyond “organization access,” is configured per-customer. Coordinate with the customer’s VOMO concierge if a specific token-management feature is needed.

​
Using the token

Every authenticated request includes the token in the Authorization header: 
GET /v1/users HTTP/1.1
Host: api.vomo.org
Authorization: Bearer eyJhbGci.....yu5CSpyHI
Accept: application/json
The full header value is the literal string Bearer (with a trailing space) followed by the token. Don’t omit the space; don’t include extra characters before or after.

​
In code

curl https://api.vomo.org/v1/users \
  -H "Authorization: Bearer $VOMO_API_TOKEN"
The token goes on every request — there’s no separate “login” flow that exchanges credentials for a session. Every API call independently authenticates.

​
Storing the token

Tokens grant full access to the customer’s VOMO data. Treat them with the same care as production database passwords.

​
Production: secrets manager

ServiceUse
AWS Secrets ManagerStandard for AWS-deployed integrations
HashiCorp VaultCloud-agnostic; works across environments
Google Secret ManagerStandard for GCP-deployed integrations
Azure Key VaultStandard for Azure-deployed integrations
Doppler, 1Password Business, etc.Smaller-team alternatives
A simple storage abstraction:
JavaScript
class VomoCredentials {
  constructor(secretsManager) {
    this.secretsManager = secretsManager;
  }

  async getToken(customerId) {
    const secret = await this.secretsManager.getSecret(
      `vomo-integration/${customerId}/api-token`
    );
    return secret.value;
  }

  async setToken(customerId, token) {
    await this.secretsManager.putSecret(
      `vomo-integration/${customerId}/api-token`,
      { value: token, updatedAt: new Date().toISOString() }
    );
  }
}
One key per customer. The hierarchical key path (vomo-integration/{customerId}/api-token) makes per-customer auditing and access control straightforward.

​
Local development: environment variables

For a developer’s local machine, an environment variable in a .env file is acceptable: 
# .env (do not commit to git)
VOMO_API_TOKEN=eyJhbGci.....yu5CSpyHI
Add .env to .gitignore. Never commit it to source control.

​
Anti-patterns

Several token-handling patterns that look reasonable but cause production issues:
Anti-patternWhy it’s bad
Hardcoding the token in source codeAnyone with repo access has the token. Hard to rotate.
Storing the token in an unencrypted database columnIf the DB is compromised, every customer’s token is exposed.
Committing the token in a config file (even encrypted)The encrypted blob in git history is recoverable; assume the key will leak eventually.
Logging the full token in application logsLogs frequently get aggregated, archived, and shared — extending exposure.
Sharing the same token across customersDefeats per-customer isolation; one compromised integration leaks everyone.
Sending the token through unencrypted channels (Slack, email, etc.)Hard to revoke once it’s in someone’s chat history.

​
Per-customer isolation

The Volunteer token is scoped to a single VOMO organization — the organization whose administrator generated it. A token for “Wayne Foundation” can only read Wayne Foundation’s data; it cannot read or write any other customer’s data. For partner integrations serving multiple customers, this means one token per customer. The integration code looks up the right token for the customer it’s currently serving.
JavaScript
async function listUsersForCustomer(customerId) {
  const token = await credentials.getToken(customerId);

  return fetch('https://api.vomo.org/v1/users', {
    headers: { Authorization: `Bearer ${token}` },
  }).then((r) => r.json());
}
The customer ID is the routing key for which token to use. Don’t try to centralize tokens; the per-customer isolation is a security feature.

​
What happens if you use the wrong token

If you accidentally use Customer A’s token while calling endpoints scoped to Customer B’s data, the response depends on how VOMO authorizes:
  • For data in Customer A’s organization, the call succeeds.
  • For data outside Customer A’s organization, the call typically returns 403 Forbidden or 404 Not Found.
The exact behavior isn’t documented in the spec, but the practical implication is: token mismatches produce errors, not silent data leaks. Still, the right discipline is to never let token mismatches happen — keep the customer→token lookup tight.

​
Token rotation

Tokens should be rotated periodically — typically every 90 days for high-stakes integrations, every 6–12 months for lower-stakes ones. The rotation flow:
1

The customer's VOMO administrator generates a new token

Through the admin portal. The old token typically remains valid during the rotation window.
2

The customer provides the new token to the partner

Same secure-handoff mechanism as initial setup.
3

The partner stores the new token alongside the old one

Both are marked as valid in the credential store.
4

The partner switches to the new token

New requests use the new token. The old token can still be used for in-flight requests if needed.
5

Confirm requests succeed with the new token

Monitor for any 401 errors that would indicate a problem.
6

The customer revokes the old token in VOMO

Once new-token requests are verified working, the administrator revokes the old token.
7

The partner removes the old token from the secrets manager

Completing the rotation cleanly.
For partner integrations with many customers, track rotation centrally:
JavaScript
async function customersNeedingRotation(maxAgeDays = 90) {
  const all = await credentials.listAll();
  const cutoff = new Date(Date.now() - maxAgeDays * 24 * 60 * 60 * 1000);

  return all.filter((c) => c.tokenUpdatedAt < cutoff);
}

// Run weekly — send reminders to customers approaching their rotation deadline
async function rotationReminderJob() {
  const dueSoon = await customersNeedingRotation(80); // 10-day warning
  for (const customer of dueSoon) {
    await emailService.send({
      to: customer.adminEmail,
      template: 'vomo-token-rotation-reminder',
      data: { lastRotated: customer.tokenUpdatedAt },
    });
  }
}
See Security and Credential Management for the broader credential management practices.

​
Handling auth failures

A 401 Unauthorized response from any endpoint means the token isn’t being accepted. Common causes:
CauseWhat to do
The token has been revokedCoordinate with the customer to issue a new one.
The token has expired (if Volunteer enforces expiration)Same — issue a new one.
The token is malformed in the request (whitespace, missing Bearer prefix, etc.)Inspect the actual request — most often the bug is on the partner side.
API access was disabled for the customer’s accountContact the customer’s VOMO concierge.
The customer’s VOMO account was suspended or deletedPause sync work for this customer and surface for human review.

​
A defensive pattern

JavaScript
async function callVolunteerApi(url, options, customerId) {
  const token = await credentials.getToken(customerId);

  const response = await fetch(url, {
    ...options,
    headers: {
      Authorization: `Bearer ${token}`,
      Accept: 'application/json',
      ...options.headers,
    },
  });

  if (response.status === 401) {
    // Don't retry — token issue, not a transient error
    await alertOps({
      severity: 'high',
      customerId,
      message: 'VOMO token rejected — credential needs refresh',
    });
    await pauseIntegrationForCustomer(customerId, 'auth_failed');
    throw new AuthError('VOMO token is not valid');
  }

  return response;
}
The critical detail: don’t retry on 401. Retries against an invalid token just produce more 401s and noise. Pause the customer’s work and alert. See Error Handling for the full error-classification pattern.

​
Handling permission errors

A 403 Forbidden response indicates the token is valid but doesn’t have permission for the specific endpoint or resource. Causes:
CauseAction
The token’s organization doesn’t have access to the requested resourceThe resource belongs to a different organization; don’t retry.
The customer’s plan doesn’t include the requested featureCoordinate with the customer’s VOMO concierge to check feature access.
The endpoint requires a higher permission tier than the token hasSame — confirm the token’s permission scope.
Like 401, 403 should not be retried. It’s a permission issue, not a transient failure.
JavaScript
if (response.status === 403) {
  await alertOps({
    severity: 'medium',
    customerId,
    endpoint: url,
    message: 'VOMO token lacks permission for this endpoint',
  });
  throw new ForbiddenError(`No permission for ${url}`);
}

​
Local development setup

For developers building or debugging integrations locally:
1

Coordinate with the customer to set up a development environment

Many customers have a dedicated test or sandbox VOMO instance for partner development. If yours doesn’t, use the production environment with care.
2

Receive a dedicated development token

Either a separate token from a sandbox account, or a clearly-marked development token from the production account.
3

Store the token in a `.env` file (gitignored)

Never commit dev tokens to source control.
4

Make a test call to confirm everything works

A GET /v1/users?per_page=1 is a minimal validation request.
5

When the work is done, revoke the development token

Coordinate with the customer’s administrator. Don’t leave development tokens active indefinitely.

​
A simple dev test

# Confirm token works
curl https://api.vomo.org/v1/users \
  -H "Authorization: Bearer $VOMO_API_TOKEN" \
  | jq '.meta.total'

# Expected: a number (the total user count)
# If you get 401: token issue
# If you get an HTML response: hit a wrong URL (perhaps missing /v1)

​
Compliance considerations

For partner integrations operating in regulated jurisdictions:
ConcernImplication
GDPR / data privacyThe token grants access to PII. Document its access in your data processing agreement with the customer.
SOC 2Token storage, rotation, and access auditing are SOC 2 control areas.
HIPAA (if applicable)If the customer’s VOMO usage touches healthcare data, the integration may inherit HIPAA obligations. Confirm with the customer’s compliance team.
The token-handling practices on this page support most common compliance frameworks. For specific requirements, consult your compliance lead.

​
Auth checklist

Walk through this when integrating with a new customer:
  • API access is enabled for the customer’s VOMO account
  • The customer’s administrator has issued a Bearer token through the admin portal
  • The token is stored in a secrets manager (production) or .env file (dev)
  • The token is never logged in plaintext
  • One token per customer — no sharing across customers
  • HTTPS is used for every request (not HTTP)
  • 401 and 403 handling pauses work rather than retrying
  • Token rotation is scheduled and tracked
  • Customer offboarding includes token revocation
  • Audit logs capture token read operations
These practices map directly to the security best-practices pattern documented in Security and Credential Management.

​
Where to go next

Base URLs

The base URL details and the /v1/ versioning convention.

First API Call

A guided first call now that authentication is set up.

Error Handling

The full error-handling pattern, including auth and permission failures.

Security and Credential Management

The deeper-dive on token storage, rotation, and operational practices.
Last modified on May 22, 2026