VonyxDocs

Authentication

Create an API key, exchange it for a token, and send the token with every request.

View this page as Markdown

Listing your numbers and placing calls need a token, which you get from your API key:

1. Create an API key at docs.vonyx.si/api-keys: a client ID and a client secret   (once)
2. Exchange the key for a token                                                    (about once a day)
3. Send the token with every request: Authorization: Bearer YOUR_TOKEN

The call details API does not use the token: it takes your client_id parameter.

1. Create an API key

Sign in at docs.vonyx.si and open API Keys. Create a key. You get a client ID and a client secret.

  • The client secret is shown only once. Store it safely. If you lose it, create a new key.
  • Create the key while signed in to the account that owns your Vonyx numbers. A key created under another account cannot see your numbers or place calls from them.

Keep the secret on your server

Keep the client secret and your tokens on your server. Never put them in a browser, a mobile app or any code your users can see.

The client ID of the key identifies the key, not your account. Your account's ID is the id in the token reply below, and the Account ID in the console's Settings.

2. Get a token

POST https://api.rylo.club/b2b/createAuthToken
Content-Type: application/json
curl -X POST https://api.rylo.club/b2b/createAuthToken \
  -H 'Content-Type: application/json' \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'
PropTypeDefault
clientId
string
-
clientSecret
string
-

Reply (200):

{
  "affectedRows": 1,
  "authToken": "YOUR_TOKEN",
  "id": "5b9d2a7e-1c4f-4e8a-9d3b-6f0e2c8a1b47",
  "expiresIn": 86400
}
FieldDescription
authTokenThe token. Send it with every request (step 3).
idYour client ID: the account the token belongs to.
expiresInHow long the token is valid, in seconds. 86400 is 24 hours.
HTTPReplyMeaningWhat to do
400{"message":"clientId and clientSecret are required"}A field is missing or empty.Send both fields.
401{"message":"Invalid client credentials"}The client ID or the client secret is wrong, or the key was revoked.Check the key, or create a new one.
429{"message":"Rate limit exceeded. Max 60 requests per minute", "code":"rate_limit_exceeded"}More than 60 token requests a minute from your IP address.Reuse your token instead of getting a new one per request; wait a minute.
502{"message":"..."}A temporary problem on our side.Try again after a few seconds.

Use the same token for all your requests until it expires; you don't need a new token per request. Get a new token shortly before expiresIn runs out, or when a request is answered with 401 and invalid or expired token.

3. Send the token

Add this header to every request to https://api.vocalstack.site/v1/numbers and https://api.vocalstack.site/v1/calls:

Authorization: Bearer YOUR_TOKEN

The word Bearer, one space, then the authToken from step 2. Always use https://.

Example

Reuses the token until shortly before it expires. A 401 changed nothing, so it is retried once with a new token.

import time
import requests  # pip install requests
 
AUTH_URL = "https://api.rylo.club/b2b/createAuthToken"
API_URL = "https://api.vocalstack.site"
CLIENT_ID = "YOUR_CLIENT_ID"          # from https://docs.vonyx.si/api-keys
CLIENT_SECRET = "YOUR_CLIENT_SECRET"  # keep it on your server
 
_token, _expires_at = None, 0.0
 
 
def get_token(force=False):
    """A valid token; a new one is fetched shortly before the old one expires."""
    global _token, _expires_at
    if force or _token is None or time.time() > _expires_at - 300:
        r = requests.post(AUTH_URL, json={"clientId": CLIENT_ID, "clientSecret": CLIENT_SECRET}, timeout=15)
        r.raise_for_status()
        d = r.json()
        _token, _expires_at = d["authToken"], time.time() + d.get("expiresIn", 86400)
    return _token
 
 
def api(method, path, timeout, body=None):
    """Calls the Vonyx API with the token. A 401 changed nothing, so it is retried once with a new token."""
    for attempt in (1, 2):
        r = requests.request(method, API_URL + path, json=body, timeout=timeout,
                             headers={"Authorization": "Bearer " + get_token(force=attempt == 2)})
        if r.status_code != 401:
            break
    return r
 
 
# Your numbers
r = api("GET", "/v1/numbers", timeout=15)
print(r.status_code, r.json())
numbers = [n["did"] for n in r.json()["data"]["numbers"]] if r.status_code == 200 else []
 
# Place a call from your first number
if numbers:
    r = api("POST", "/v1/calls", timeout=35, body={
        "did": numbers[0],
        "phone_number": "9876543210",
        "websocket_url": "wss://agent.example.com/ws",
        "sample_rate": 8000,
        "webhook_url": "https://example.com/vonyx/call-status",
    })
    print(r.status_code, r.json())

Revoking a key

Revoke a key at docs.vonyx.si when you no longer need it, or if its secret may have been exposed. Revoking stops new tokens from that key. A token already issued from it stays valid until it expires, at most 24 hours later.

On this page