# Getting started

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**

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

**Node**

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

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

**Python**

```python
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**

```php
<?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 | Required | Description |
| --- | --- | --- | --- |
| `client_ip` | string | yes | The address we see your request coming from. The allow-list is checked against this address. |
| `forwarded_for` | array of strings | yes | The `X-Forwarded-For` chain we received, left to right, for troubleshooting. |
| `company_id` | integer | yes | Your company id. |
| `ip_restricted` | boolean | yes | True when this key is locked to addresses. |
| `allowed_ips` | array of strings | yes | The addresses this key is locked to. Empty means any address. |

**Example**

```json
{
  "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.

#### 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.