Developer Portal API

The Developer Portal API allows you to manage your developer resources - applications, API keys, webhook endpoints, and more.

These endpoints require JWT authentication with the MANAGE_DEVELOPER_KEYS permission and a valid business context.

All endpoints are prefixed with:


/api/developer

Catalogs

Two read-only endpoints return the canonical lists your UI can render - so you never have to hardcode scopes or event names.


GET /api/developer/scopes

Returns every assignable API-key scope with a label, group, and risk level.


GET /api/developer/webhook-events

Returns every webhook event you can subscribe to, with a label and group. See the full list in the Webhooks event catalog.

Developer Apps

Developer apps group your API keys and webhook endpoints by application and environment.

List Apps


GET /api/developer/apps

Response:


{
  "message": "Developer apps retrieved",
  "data": [
    {
      "id": "uuid",
      "businessId": "uuid",
      "name": "My App",
      "environment": "test",
      "status": "active",
      "isDefault": false,
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ]
}

Create App


POST /api/developer/apps

Request Body:


{
  "name": "My App",
  "environment": "test"
}

Field	Type	Required	Description
`name`	string	Yes	App name (2–120 characters)
`environment`	`"test"` \| `"live"`	Yes	Target environment

API Keys

List API Keys


GET /api/developer/api-keys?developer_app_id=uuid

Query Parameters:

Parameter	Type	Description
`developer_app_id`	uuid	Filter by developer app (optional)

Create API Key


POST /api/developer/api-keys

Creating, rotating, or viewing API key secrets requires recent password verification. You will be prompted to re-enter your password.

Request Body:


{
  "name": "Production Key",
  "developer_app_id": "uuid",
  "environment": "live",
  "scopes": ["vox:calls:read", "vox:calls:create"],
  "allowed_origins": ["https://myapp.com"],
  "allowed_ip_ranges": ["203.0.113.0/24"],
  "expires_at": "2027-01-01T00:00:00.000Z"
}

Field	Type	Required	Description
`name`	string	Yes	Key name (2–120 characters)
`developer_app_id`	uuid	No	Associate with an app
`environment`	`"test"` \| `"live"`	Yes	Key environment
`scopes`	string[]	Yes	Permission scopes (min 1) - see the scope catalog
`allowed_origins`	string[]	No	Restrict by origin hostname
`allowed_ip_ranges`	string[]	No	Restrict by IP CIDR ranges
`expires_at`	ISO date	No	Key expiration date
`withdrawal_policy`	object	No	Per-key withdrawal limits - required to use `wallet:withdrawals:create`

A live key granted a finance-write scope (payouts:write or wallet:withdrawals:create) must include allowed_ip_ranges. Creation is rejected otherwise.

The withdrawal_policy object gates API-initiated withdrawals (see Wallet & payouts → Withdrawals):


{
  "withdrawal_policy": {
    "max_per_transaction": 50000,
    "max_per_day": 200000,
    "currency": "NGN",
    "allowed_payout_account_ids": ["pa1a2b3c-..."]
  }
}

Limits: a business may hold at most 10 active keys per environment.

Get API Key


GET /api/developer/api-keys/:id

Update API Key


PATCH /api/developer/api-keys/:id

Allows updating name, scopes, allowed_origins, allowed_ip_ranges, and expires_at. Note: developer_app_id and environment cannot be changed after creation.

Rotate API Key


POST /api/developer/api-keys/:id/rotate

Rotates the secret while keeping the same public key. The old secret is immediately invalidated. Requires password re-verification.

View API Key Secret


POST /api/developer/api-keys/:id/view-secret

Returns the currently stored secret (encrypted at rest). Requires password re-verification.

Revoke API Key


POST /api/developer/api-keys/:id/revoke

Immediately revokes the key. Revoked keys cannot be updated or rotated.

Delete API Key


DELETE /api/developer/api-keys/:id

Permanently deletes the key and its associated data.

Webhook Endpoints

List Webhook Endpoints


GET /api/developer/webhook-endpoints?developer_app_id=uuid

Create Webhook Endpoint


POST /api/developer/webhook-endpoints

Request Body:


{
  "name": "Call Events Handler",
  "developer_app_id": "uuid",
  "url": "https://myapp.com/webhooks/vox",
  "environment": "live",
  "events": ["vox.call.completed", "vox.call.failed"]
}

Field	Type	Required	Description
`name`	string	Yes	Endpoint name
`developer_app_id`	uuid	No	Associate with an app
`url`	string (URL)	Yes	HTTPS callback URL
`environment`	`"test"` \| `"live"`	Yes	Target environment
`events`	string[]	Yes	Event types to subscribe to

Rate Limits: Maximum 8 active endpoints per environment.

Update Webhook Endpoint


PATCH /api/developer/webhook-endpoints/:id

Disable Webhook Endpoint


POST /api/developer/webhook-endpoints/:id/disable

Disables the endpoint without deleting it.

Webhook Settings


GET /api/developer/webhook-settings?developer_app_id=uuid

Returns webhook signing settings, including the signing secret prefix and rotation status.

Rotate Webhook Secret


POST /api/developer/webhook-settings/:environment/rotate-secret

Requires password re-verification.

Request Body:


{
  "developer_app_id": "uuid"
}

View Webhook Secret


POST /api/developer/webhook-settings/:environment/view-secret

Requires password re-verification.

Webhook Deliveries

List Deliveries


GET /api/developer/webhook-deliveries?developer_app_id=uuid

Returns the last 100 delivery attempts.

Resend Delivery


POST /api/developer/webhook-deliveries/:id/resend

Queues the webhook event for redelivery.

Events

List Events


GET /api/developer/events?api_key_id=uuid&event_type=api_key.created&page=1&per_page=50

Returns a paginated audit log of developer actions (key creation, rotation, webhook management, etc.).

Query Parameters:

Parameter	Type	Description
`api_key_id`	uuid	Filter by API key
`event_type`	string	Filter by event type
`page`	number	Page number (default: 1)
`per_page`	number	Items per page (1–100, default: 50)
`start_date`	ISO date	Filter from date
`end_date`	ISO date	Filter to date

Response:


{
  "success": true,
  "message": "Developer API key events retrieved",
  "data": [
    {
      "id": "uuid",
      "businessId": "uuid",
      "developerApiKeyId": "uuid",
      "actorUserId": "uuid",
      "actorName": "John Doe",
      "eventType": "api_key.created",
      "title": "API key created",
      "ipAddress": "203.0.113.1",
      "metadata": {
        "environment": "live",
        "scopes": ["vox:calls:read"]
      },
      "createdAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "meta": {
    "total": 50,
    "page": 1,
    "perPage": 50,
    "totalPages": 1,
    "hasMore": false
  }
}

Usage Analytics


GET /api/developer/usage?days=30&developer_app_id=uuid

Returns aggregated API usage data, grouped by day, environment, method, endpoint, and status family.

Query Parameters:

Parameter	Type	Description
`days`	number	Lookback period (1–90, default: 30)
`developer_app_id`	uuid	Filter by app

Response:


{
  "message": "Developer API usage retrieved",
  "data": [
    {
      "date": "2026-01-15",
      "environment": "live",
      "method": "GET",
      "endpoint": "/v1/vox/calls",
      "statusFamily": "2xx",
      "requestCount": 150,
      "errorCount": 3,
      "totalLatencyMs": 45000
    }
  ]
}