VOvoipbin
NumberProvider

Store the secret of a number provider

Changed on

Stores the secret (for example the API token) of the given number provider, encrypted. The secret is write-only: it is never returned, logged or placed in an event. The response tells only has_secret, the key_version that encrypted it and who changed it. The value is trimmed of surrounding whitespace, and must be 1 to 1024 bytes long after that (multi-byte characters count per byte). The provider's required config keys must already be set (see PUT /number_providers/{provider_name}), otherwise the request is rejected with 400. When the platform has no encryption key the request is answered with 503 before the config rule is checked. Replacing the secret with the token of another account makes the numbers purchased through the previous account impossible to release. Requires the project super admin permission.

put/number_providers/{provider_name}/secret

Request

  • Base URL
    https://api.voipbin.net/v1.0
  • URL
    https://api.voipbin.net/v1.0/number_providers/{provider_name}/secret
  • Auth
    none declared

Path parameters

provider_namestring required
Example:telnyx

The name of the number provider. Returned from the provider_name field of the GET /number_providers response. Only the providers the platform supports are accepted (for example telnyx).

Request body

secretstring required

The secret (for example the API token) of the provider. Trimmed of surrounding whitespace; 1 to 1024 bytes after that.

Example request

{
  "secret": "example-secret-token"
}

Response

The number provider with the secret stored. The secret is not included.

provider_namestring

The name of the number provider.

enabledboolean

Whether the provider takes part in the number purchase.

priorityinteger

The purchase order. A lower value is tried first; ties are ordered by provider_name.

configobject

The non-secret settings of the provider (for example the Telnyx connection_id). Omitted when empty.

has_secretboolean

Whether a secret is stored through the API. The secret itself is never returned.

key_versioninteger

The version of the encryption key that encrypted the stored secret. 0 when no secret is stored.

credential_source'db' | 'env' | 'none' | 'db_undecryptable'

Where the credentials of the number provider come from. db is the secret stored through the API, env is the platform environment, none means no credential exists, and db_undecryptable means a stored secret exists but cannot be decrypted (the provider is unusable until the encryption key is restored or the stored secret is deleted).

usableboolean

Whether the provider can currently serve (enabled, with a usable credential and its required config; Twilio needs sid and trunk_sid, which the environment credentials cannot give). An enabled and usable provider takes part in number purchase.

updated_bystring uuid

The agent who last changed enabled, priority or config. The agent ID returned from the GET /agents response. Omitted when never changed.

secret_updated_bystring uuid

The agent who last changed the secret. The agent ID returned from the GET /agents response. Omitted when never changed.

tm_updatestring date-time

The timestamp of the last change of the setting, including a secret change. Omitted when never changed.

tm_secret_updatestring date-time

The timestamp of the last secret change. Omitted when never changed.

Example response

{
  "provider_name": "telnyx",
  "enabled": true,
  "priority": 10,
  "config": {
    "connection_id": "1234567890123456789"
  },
  "has_secret": true,
  "key_version": 1,
  "credential_source": "db",
  "usable": true,
  "updated_by": "550e8400-e29b-41d4-a716-446655440000",
  "secret_updated_by": "00000000-0000-4000-8000-000000000002",
  "tm_update": "2026-01-02T03:04:05.000000Z",
  "tm_secret_update": "2026-01-03T04:05:06.000000Z"
}

Changes