---
title: "Store the secret of a number provider"
method: PUT
path: "/number_providers/{provider_name}/secret"
tags: ["NumberProvider"]
---

# Store the secret of a number provider

`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

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.

## Path parameters

- `provider_name` string, required

## Request body

- NumberManagerNumberProviderSecretRequest: The secret to store. It is write-only and never returned.
  - `secret` string, required: The secret (for example the API token) of the provider. Trimmed of surrounding whitespace; 1 to 1024 bytes after that.

## Response `200`

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

- NumberManagerNumberProvider: The setting of a number provider. It never contains a secret.
  - `provider_name` string: The name of the number provider.
  - `enabled` boolean: Whether the provider takes part in the number purchase.
  - `priority` integer: The purchase order. A lower value is tried first; ties are ordered by `provider_name`.
  - `config` object: The non-secret settings of the provider (for example the Telnyx `connection_id`). Omitted when empty.
  - `has_secret` boolean: Whether a secret is stored through the API. The secret itself is never returned.
  - `key_version` integer: 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).
  - `usable` boolean: 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_by` string, 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_by` string, uuid: The agent who last changed the secret. The agent ID returned from the `GET /agents` response. Omitted when never changed.
  - `tm_update` string, date-time: The timestamp of the last change of the setting, including a secret change. Omitted when never changed.
  - `tm_secret_update` string, date-time: The timestamp of the last secret change. Omitted when never changed.

## Other responses

- `400`: Invalid request (INVALID_ARGUMENT).
- `401`: Authentication required (UNAUTHENTICATED).
- `403`: Insufficient permission (PERMISSION_DENIED).
- `404`: Resource not found (NOT_FOUND).
- `500`: Internal error (INTERNAL).
- `503`: Upstream unavailable (UNAVAILABLE).

## Changes

- **2026-10-25** `54599fe70445`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/voipbin/apis/voipbin-api/changes/number_providers/:provider_name/secret/put.md)

---

[API](https://skmtc.dev/voipbin/apis/voipbin-api.md) - [All operations](https://skmtc.dev/voipbin/apis/voipbin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voipbin/apis/voipbin-api/revisions/11338be3ceae?raw)