Start

Getting started

Read from the API’s own reference file every hour.

Check your key and the address we see you coming from. Start here, and come back here when a request answers 401 or 403.

Check your key

GET/v1/whoami

Shows the address we see your request coming from, your company id, and whether this key is locked to addresses.

Call it first when you set up a key, and before you add an IP allow-list, so you enter the right address. It is also the first thing to check when requests start answering 403.

Every key may call this route, whatever its scopes. client_ip is the address the allow-list is checked against. forwarded_for is the whole X-Forwarded-For chain we received, for troubleshooting.

Request

curl https://api.vocatech.com/v1/whoami \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch("https://api.vocatech.com/v1/whoami", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

console.log(res.status, await res.json());

import requests

r = requests.get(
    "https://api.vocatech.com/v1/whoami",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(r.status_code, r.json())

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://api.vocatech.com',
    'headers' => ['Authorization' => 'Bearer YOUR_API_KEY'],
    'http_errors' => false,
]);

$res = $client->get('/v1/whoami');

echo $res->getStatusCode(), PHP_EOL, $res->getBody(), PHP_EOL;

Answers

200

Your key works. This is what we see.

Field	Type	Description
`client_ip` required	string	The address we see your request coming from. The allow-list is checked against this address.
`forwarded_for` required	array of strings	The `X-Forwarded-For` chain we received, left to right, for troubleshooting.
`company_id` required	integer	Your company id.
`ip_restricted` required	boolean	True when this key is locked to addresses.
`allowed_ips` required	array of strings	The addresses this key is locked to. Empty means any address.

Example

{
  "client_ip": "203.0.113.24",
  "forwarded_for": [
    "203.0.113.24"
  ],
  "company_id": 1234567890,
  "ip_restricted": true,
  "allowed_ips": [
    "203.0.113.24",
    "2001:db8::10"
  ]
}

401

No key, or a key that is wrong or turned off.

403

The request came from an address not on the key's allow-list.

429

A rate limit was reached. Wait Retry-After seconds. The body names the counter, the window and the limit.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

503

Try again shortly. The key could not be checked just now (Retry-After: 5), or a service this route needs could not be reached.

Header	Type	Description
`Retry-After`	integer	Seconds to wait before you try again.

Before thisOverview Next Calls