Authentication
Create an API key, exchange it for a token, and send the token with every request.
Listing your numbers and placing calls need a token, which you get from your API key:
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
| Prop | Type | Default |
|---|---|---|
clientId | string | - |
clientSecret | string | - |
Reply (200):
| Field | Description |
|---|---|
authToken | The token. Send it with every request (step 3). |
id | Your client ID: the account the token belongs to. |
expiresIn | How long the token is valid, in seconds. 86400 is 24 hours. |
| HTTP | Reply | Meaning | What 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:
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.
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.