Accesskey

Manage API access keys for authenticating requests to the VoIPBIN API. Access keys are long-lived Bearer tokens used in the Authorization header or as accesskey query parameters.

API Reference: Accesskey endpoints

Accesskey API Overview

Note

AI Context

Complexity: Low
Cost: Free (no charges for accesskey operations)
Async: No. All accesskey operations are synchronous and return immediately.

The Accesskey API provides a secure and efficient way to authenticate and interact with the VoIPBIN platform. It utilizes access keys as API tokens to enable authorized access to API endpoints. This ensures seamless integration while maintaining the security and integrity of your operations.

Note

AI Implementation Hint

Use the accesskey query parameter (not the token parameter) when authenticating with an access key. The token parameter is used for session-based authentication, while accesskey is for API key-based authentication. Do not confuse the two.

API Usage

To use the Accesskey, pass the accesskey in the query parameters of your API requests. Below is an example usage:

Example Request

curl --location 'https://api.voipbin.net/v1.0/calls?accesskey=vb_a3Bf9xKmPq2nR7sT4wYzLp8mN5qR1xWe'

Description of Parameters

Accesskey: The accesskey query parameter must contain the token issued for the customer. This token uniquely identifies and authorizes the request. Tokens are prefixed with vb_ for identification.

Authentication

The accesskey serves as the authentication credential. Tokens are hashed server-side using SHA-256 before storage. The full token is only shown once at creation time. Store it securely and avoid exposing it in client-side code or public repositories.

Lifecycles and Expiry

Accesskeys come with lifecycle timestamps:

tm_create: The creation timestamp.
tm_update: The last updated timestamp.
tm_expire: The expiration timestamp. Ensure you rotate keys before this date.
tm_delete: The deletion timestamp, if applicable.

Note

AI Implementation Hint

When creating an accesskey, the expire field is specified in seconds (e.g., 31536000 for one year). The API returns tm_expire as an ISO 8601 timestamp calculated from the creation time plus the expiry duration. Always check tm_expire before using a key to avoid authentication failures with expired tokens.

Notes

Always use HTTPS to ensure secure communication.
Tokens should be rotated periodically to enhance security.
If a token is lost, delete the key and create a new one. The full token cannot be retrieved after creation.

Struct

Accesskey

{
   "id": "5f1f8f7e-9b3d-4c60-8465-b69e9f28b6db",
   "customer_id": "a1d9b2cd-4578-4b23-91b6-5f5ec4a2f840",
   "name": "My API Key",
   "detail": "For accessing reporting APIs",
   "token_prefix": "vb_a3Bf9xKm",
   "tm_expire": "2027-04-28T01:41:40.503790Z",
   "tm_create": "2026-04-28T01:41:40.503790Z",
   "tm_update": "2026-04-28T01:41:40.503790Z",
   "tm_delete": "9999-01-01T00:00:00.000000Z"
}

id (UUID): The accesskey’s unique identifier. Returned when creating an accesskey via POST /accesskeys or when listing accesskeys via GET /accesskeys.
customer_id (UUID): The customer that owns this accesskey. Obtained from the id field of GET /customers.
name (String, Optional): An optional human-readable name for the accesskey. Useful for identification in multi-key environments.
detail (String, Optional): An optional description of the accesskey’s intended use or purpose.
token (String, Optional): The full API token credential. Only returned once at creation time via POST /accesskeys. Store it securely and immediately. If lost, delete the key and create a new one.
token_prefix (String): A short prefix of the token (e.g., vb_a3Bf9xKm) for identification. Always returned in GET responses.
tm_expire (String, ISO 8601): Timestamp when the accesskey will expire. After this time, the key will no longer be valid for authentication.
tm_create (String, ISO 8601): Timestamp when the accesskey was created.
tm_update (String, ISO 8601): Timestamp when the accesskey was last updated.
tm_delete (String, ISO 8601): Timestamp when the accesskey was deleted, if applicable.

Note

AI Implementation Hint

A tm_delete value of 9999-01-01T00:00:00.000000Z indicates the accesskey has not been deleted and is still active. This sentinel value is used across all VoIPBIN resources to represent “not yet occurred.”

Note

AI Implementation Hint

The token field is only present in the response to POST /accesskeys (creation). All subsequent GET /accesskeys and GET /accesskeys/{id} responses will NOT include the token field. Use token_prefix to identify which key is which. If the token is lost, delete the key via DELETE /accesskeys/{id} and create a new one.

Tutorial

Before managing accesskeys, you need:

An authentication token. Obtain one via POST /auth/login or use an existing access key from GET /accesskeys.
(For creation) The expire duration in seconds (e.g., 31536000 for one year).

Note

AI Implementation Hint

The expire field in the create request is in seconds, not a timestamp. For example, use 86400 for a one-day key, 2592000 for 30 days, or 31536000 for one year. The API calculates the actual expiration timestamp and returns it in the tm_expire field.

Create, Retrieve, and Manage Accesskeys

This tutorial demonstrates how to create an access key, retrieve a list of access keys, and retrieve a specific access key using the API. All requests must include the accesskey query parameter for authentication.

Create an Accesskey

Use the following command to create a new access key. The expire parameter specifies the duration in seconds before the key expires.

$ curl -k --location --request POST 'https://api.voipbin.net/v1.0/accesskeys?accesskey=<your-access-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "My New Accesskey",
    "detail": "This key is used for reporting",
    "expire": 31536000
}'

Example Response:

{
    "id": "2f1f8f7e-9b3d-4c60-8465-b69e9f28b6dc",
    "customer_id": "a1d9b2cd-4578-4b23-91b6-5f5ec4a2f840",
    "name": "My New Accesskey",
    "detail": "This key is used for reporting",
    "token": "vb_a3Bf9xKmPq2nR7sT4wYzLp8mN5qR1xWe",
    "token_prefix": "vb_a3Bf9xKm",
    "tm_expire": "2027-12-01T10:15:30.123456Z",
    "tm_create": "2026-12-01T10:15:30.123456Z",
    "tm_update": "2026-12-01T10:15:30.123456Z",
    "tm_delete": "9999-01-01T00:00:00.000000Z"
}

Note

AI Implementation Hint

The token field is only returned in this creation response. Store it securely and immediately. You will not be able to retrieve the full token again. If the token is lost, delete the key via DELETE /accesskeys/{id} and create a new one. Use token_prefix to identify which key is which in subsequent requests.

Get a List of Accesskeys

Retrieve all existing access keys associated with your account. Include the accesskey query parameter in the request URL for authentication.

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/accesskeys?accesskey=<your-access-key>'

Example Response:

{
    "result": [
        {
            "id": "2f1f8f7e-9b3d-4c60-8465-b69e9f28b6dc",
            "customer_id": "a1d9b2cd-4578-4b23-91b6-5f5ec4a2f840",
            "name": "My New Accesskey",
            "detail": "This key is used for reporting",
            "token_prefix": "vb_a3Bf9xKm",
            "tm_expire": "2027-12-01T10:15:30.123456Z",
            "tm_create": "2026-12-01T10:15:30.123456Z",
            "tm_update": "2026-12-01T10:15:30.123456Z",
            "tm_delete": "9999-01-01T00:00:00.000000Z"
        }
    ],
    "next_page_token": null
}

Get a Specific Accesskey

Retrieve details of a specific access key using its unique ID. Include the accesskey query parameter for authentication.

$ curl -k --location --request GET 'https://api.voipbin.net/v1.0/accesskeys/2f1f8f7e-9b3d-4c60-8465-b69e9f28b6dc?accesskey=<your-access-key>'

Example Response:

{
    "id": "2f1f8f7e-9b3d-4c60-8465-b69e9f28b6dc",
    "customer_id": "a1d9b2cd-4578-4b23-91b6-5f5ec4a2f840",
    "name": "My New Accesskey",
    "detail": "This key is used for reporting",
    "token_prefix": "vb_a3Bf9xKm",
    "tm_expire": "2027-12-01T10:15:30.123456Z",
    "tm_create": "2026-12-01T10:15:30.123456Z",
    "tm_update": "2026-12-01T10:15:30.123456Z",
    "tm_delete": "9999-01-01T00:00:00.000000Z"
}