Authentication

Every request to the Voicebip API must include a valid API key in the Authorization header using the Bearer scheme.

API Key Format

Voicebip issues two types of API keys:

API keys are generated via the Create API Key endpoint or the Voicebip Dashboard.

Making Authenticated Requests

Include your API key in the Authorization header:

$
curl -X GET "https://api.voicebip.com/v1/agents" \
>
  -H "Authorization: Bearer pk_live_your_api_key_here"

Base URL

Sandbox mode is activated by your key prefix, not a different base URL. Use a pk_test_ key against the same https://api.voicebip.com/v1 endpoint — the API detects the prefix and routes requests through the sandbox pipeline automatically.

All endpoints are versioned under /v1/. All timestamps are ISO 8601 UTC. All phone numbers use E.164 format.

Sandbox Mode

Use a pk_test_ key to enter sandbox mode automatically. In sandbox mode:

• Agent and number CRUD works identically to production
• Calls and messages simulate the full lifecycle (webhook events fire normally)
• Webhook signatures use real HMAC-SHA256 — your verification code works unchanged
• No real SIP/RTP calls, no real SMPP messages, no billing charges
• Sandbox numbers are provisioned from reserved test pools: +234800000xxxx (mobile virtual), +234100000xxxx (Lagos DID)

Switch to production by replacing pk_test_ with pk_live_ in your Authorization header. No other code changes needed.

Error on Invalid Key

If the API key is missing, malformed, revoked, or expired, the API returns 401 Unauthorized:

1
{
2
  "error_code": "UNAUTHENTICATED",
3
  "message": "Invalid or missing API key",
4
  "request_id": "req_abc123def456",
5
  "documentation_url": "https://docs.voicebip.com/errors/UNAUTHENTICATED"
6
}

Request IDs

Every API response includes a request_id (format: req_{nanoid}). Include this when contacting support — it links to the full trace in our observability stack.

API Key Lifecycle

Key revocation takes effect within 60 seconds (Redis cache TTL).

Rate Limits

Requests are rate-limited per workspace using a sliding window:

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header indicating seconds until the next allowed request.

1
{
2
  "error_code": "RATE_LIMITED",
3
  "message": "Rate limit exceeded. Retry after 12 seconds.",
4
  "request_id": "req_xyz789",
5
  "documentation_url": "https://docs.voicebip.com/errors/RATE_LIMITED"
6
}

Session Management

These endpoints let you inspect the authenticated identity and revoke all active sessions. All three require a valid API key in the Authorization header.

GET /v1/auth/me

Returns the user and workspace associated with the API key used to make the request. Use this to verify that a key is valid and to retrieve workspace metadata without making a business-logic call.

$
curl -X GET "https://api.voicebip.com/v1/auth/me" \
>
  -H "Authorization: Bearer pk_live_your_api_key_here"

Response — 200 OK

1
{
2
  "user_id": "usr_abc123",
3
  "email": "owner@example.com",
4
  "workspace_id": "ws_xyz789",
5
  "role": "owner",
6
  "verified": true,
7
  "created_at": "2024-11-01T09:00:00Z"
8
}

Error codes

POST /v1/auth/logout-all

Revokes all active sessions for the workspace owner. Internally this increments the token revision counter, which causes every existing JWT issued for this account to be rejected by the API gateway on its next request. The current API key’s JWT is also immediately added to the Redis blocklist so invalidation is effective within milliseconds rather than waiting for the cache TTL.

Use this endpoint when responding to a suspected credential compromise or during a planned credential rotation.

No request body is required.

$
curl -X POST "https://api.voicebip.com/v1/auth/logout-all" \
>
  -H "Authorization: Bearer pk_live_your_api_key_here"

Response — 200 OK

1
{
2
  "message": "All sessions have been revoked."
3
}

Error codes

POST /v1/auth/delete-account

Permanently deletes the user account and soft-deletes the associated workspace. This operation cannot be undone.

The request body must include the account password as a confirmation step. An incorrect password returns 401 INVALID_PASSWORD before any deletion takes place.

$
curl -X POST "https://api.voicebip.com/v1/auth/delete-account" \
>
  -H "Authorization: Bearer pk_live_your_api_key_here" \
>
  -H "Content-Type: application/json" \
>
  -d '{"password": "your-account-password"}'

Request body

Response — 200 OK

1
{
2
  "message": "Account deleted successfully."
3
}

Error codes