Authentication

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

Concern	How Volunteer handles it
Auth mechanism	Bearer token in `Authorization` header
Token format	JWT (per `eyJhbGci...` prefix in examples)
Token issuance	Generated in the VOMO admin portal by the customer’s administrator
Token scope	A single VOMO organization
Token expiration	Not documented in the spec
Token rotation	Manual — administrator regenerates and provides new token
Revocation	Done 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:

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.

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.

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.

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"

const response = await fetch('https://api.vomo.org/v1/users', {
  headers: {
    Authorization: `Bearer ${process.env.VOMO_API_TOKEN}`,
  },
});

import requests

response = requests.get(
    'https://api.vomo.org/v1/users',
    headers={'Authorization': f'Bearer {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

Service	Use
AWS Secrets Manager	Standard for AWS-deployed integrations
HashiCorp Vault	Cloud-agnostic; works across environments
Google Secret Manager	Standard for GCP-deployed integrations
Azure Key Vault	Standard 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-pattern	Why it’s bad
Hardcoding the token in source code	Anyone with repo access has the token. Hard to rotate.
Storing the token in an unencrypted database column	If 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 logs	Logs frequently get aggregated, archived, and shared — extending exposure.
Sharing the same token across customers	Defeats 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:

The customer's VOMO administrator generates a new token

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

The customer provides the new token to the partner

Same secure-handoff mechanism as initial setup.

The partner stores the new token alongside the old one

Both are marked as valid in the credential store.

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.

Confirm requests succeed with the new token

Monitor for any 401 errors that would indicate a problem.

The customer revokes the old token in VOMO

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

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:

Cause	What to do
The token has been revoked	Coordinate 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 account	Contact the customer’s VOMO concierge.
The customer’s VOMO account was suspended or deleted	Pause 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:

Cause	Action
The token’s organization doesn’t have access to the requested resource	The resource belongs to a different organization; don’t retry.
The customer’s plan doesn’t include the requested feature	Coordinate with the customer’s VOMO concierge to check feature access.
The endpoint requires a higher permission tier than the token has	Same — 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:

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.

Receive a dedicated development token

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

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

Never commit dev tokens to source control.

Make a test call to confirm everything works

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

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:

Concern	Implication
GDPR / data privacy	The token grants access to PII. Document its access in your data processing agreement with the customer.
SOC 2	Token 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.

Getting Started

Core Concepts

Workflows

Polling and Sync

Recipes

Best Practices

At a glance

Obtaining a token

Using the token

In code

Storing the token

Production: secrets manager

Local development: environment variables

Anti-patterns

Per-customer isolation

What happens if you use the wrong token

Token rotation

Handling auth failures

A defensive pattern

Handling permission errors

Local development setup

A simple dev test

Compliance considerations

Auth checklist

Where to go next

Base URLs

First API Call

Error Handling

Security and Credential Management

​At a glance

​Obtaining a token

​Using the token

​In code

​Storing the token

​Production: secrets manager

​Local development: environment variables

​Anti-patterns

​Per-customer isolation

​What happens if you use the wrong token

​Token rotation

​Handling auth failures

​A defensive pattern

​Handling permission errors

​Local development setup

​A simple dev test

​Compliance considerations

​Auth checklist

​Where to go next

Base URLs

First API Call

Error Handling

Security and Credential Management

At a glance

Obtaining a token

Using the token

In code

Storing the token

Production: secrets manager

Local development: environment variables

Anti-patterns

Per-customer isolation

What happens if you use the wrong token

Token rotation

Handling auth failures

A defensive pattern

Handling permission errors

Local development setup

A simple dev test

Compliance considerations

Auth checklist

Where to go next