API tokens

Personal access tokens authenticate server-to-server requests to the Voicegram public API and back the Zapier app. Each token is a long, random, unguessable string, scoped to a single account, and can be revoked instantly.

What is a personal access token?

A personal access token (PAT) is a bearer credential that authenticates requests to the Voicegram public API on behalf of one account. Tokens are long, random, unguessable strings. Voicegram never stores the plaintext after creation, so the token is shown to you once and cannot be retrieved later.

Only account admins can create or revoke tokens. Tokens inherit the admin role on the account, so treat them as fully privileged credentials.

Token format

Every Voicegram PAT has the form vg_pat_ followed by 64 hexadecimal characters. The vg_pat_ prefix lets secret scanners (and you) recognize a Voicegram token at a glance.

vg_pat_a3f9b1c2d4e58f7081a2b3c4d5e6f7081a2b3c4d5e6f70811234567890abcdef

Creating a token

1. Sign in to your dashboard and visit Integrations, API access.
2. Click New token. Give the token a descriptive name (for example, "Zapier production" or "CRM sync script") so future you can identify it in the list.
3. Pick an expiration. The default is "Never expires." You can also choose 30 days, 90 days, or 1 year. Tokens with an expiration will trigger email reminders before they lapse.
4. Click Create token. Copy the plaintext value immediately. The dashboard only shows it once. If you lose it, revoke it and create a new one.

Using a token

Send the token in the Authorization header on every request. Voicegram uses standard Bearer authentication.

curl https://www.voicegram.io/api/v1/me \
  -H "Authorization: Bearer vg_pat_<your_token>"

// Node 18+ (built-in fetch)
const res = await fetch('https://www.voicegram.io/api/v1/me', {
  headers: {
    Authorization: `Bearer ${process.env.VOICEGRAM_PAT}`,
  },
});
const me = await res.json();
console.log(me);

import os, requests

res = requests.get(
    "https://www.voicegram.io/api/v1/me",
    headers={"Authorization": f"Bearer {os.environ['VOICEGRAM_PAT']}"},
)
res.raise_for_status()
print(res.json())

The full set of endpoints, request schemas, and response shapes is in the OpenAPI 3.1 spec.

Expiration and reminders

Expirations are optional. If you set one, Voicegram emails the account admin twice before the token expires:

• 30 days before expiry, as a heads-up that the token will need rotation.
• 7 days before expiry, as a final reminder.

Reminders are only sent for tokens with a finite expiration. A token with no expiry will not generate any reminder mail.

Revocation

Revocation is instant. Click Revoke next to a token in the dashboard and any in-flight or future request bearing that token will fail with 401 Unauthorized. There is no grace period. Revoked tokens cannot be re-enabled. Issue a new token instead.

If a token is ever exposed (committed to git, pasted into a public Slack, etc.), revoke it immediately and issue a new one.

Limits

• 20 active tokens per account. Revoke an old token before creating a new one once you hit the cap.
• 60 requests per minute per account per endpoint. Burst traffic above this returns 429 rate_limited. The rate limiter is per-endpoint, so reading /me does not eat into your budget for /voicegrams/recent.
• 10 token creations per minute per account. A generous ceiling for legitimate rotation, with a backstop against automated abuse.

Security best practices

• Never commit a token to git. If you do, revoke it immediately and rotate.
• Store tokens in your secret manager or your platform's environment variable store, never in source code.
• Rotate tokens periodically. Setting a finite expiration forces this hygiene automatically.
• Revoke any token whose machine, laptop, or CI runner is decommissioned, lost, or compromised.
• Use one token per integration. A separate token for Zapier vs. your CRM sync vs. an internal cron job makes it cheap to revoke just the affected scope.