# Fetch the API account your token belongs to

- Endpoint: `GET /v1/api-account/validate-me`
- Production: `https://api.main-team.org/v1/api-account/validate-me`
- Sandbox: `https://apisnd.main-team.org/v1/api-account/validate-me`
- Operation: `getCurrentApiAccount` (API account)
- Authentication: `Authorization: Bearer <token>`, a short-lived token you sign with your API key and secret
- Permission: `api/*:$org:$ID`

## Description

The account whose `apiKey` signed the token: its `_id`, `apiKey`, `companyName`, `scopes`, `roles` and `isActive`, never its `apiSecret`. Call it to check that your tokens are accepted and which account they name.

**The one operation without the envelope.** The account is the whole body, not `data` inside `{ success, message, data }`.

`roles` are the grants an operator gave your account, each `{ effect, action, target, authorized? }`. When an operation answers `403 forbidden` with "Insufficient role permissions", compare them with its `x-permission`: no `allow` role matched it on that organization, or a `disallow` role did.

It needs the `api/*` permission, which only a role whose action is `api/*`, `*/*` or `*` grants; a role for the student or exam operations does not. A change an operator makes to your account, to its roles or deactivating it, can take up to 60 seconds to reach this and every other operation.

## Response

`200` The object itself, not wrapped in the `{ success, message, data }` envelope every other operation answers with.

```json
{
  "_id": "6650a1b2c3d4e5f6a7b8c9f0",
  "apiKey": "key_EXAMPLEexample0123456789",
  "companyName": "Example Learning Ltd",
  "scopes": [],
  "roles": [
    {
      "effect": "allow",
      "action": "student/*",
      "target": "mto",
      "authorized": "6650a1b2c3d4e5f6a7b8c9f0"
    }
  ],
  "isActive": true
}
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| 401 | [`unauthorized`](https://hub.main-team.org/api/errors#unauthorized) | The token is missing or malformed, is not signed with your account’s `apiSecret`, breaks the `iat` and `exp` rules, has expired or been revoked, or its account is not active. All of these answer the same. |
| 403 | [`forbidden`](https://hub.main-team.org/api/errors#forbidden) | The token is valid, but no role on your account allows `api/*` on `mto`, the organization every operation without `:organizationId` acts on, or a role denies it. |
| 429 | [`too_many_requests`](https://hub.main-team.org/api/errors#too_many_requests) | Your account has made more than 100 requests to this operation in the current 60-second window. Wait the seconds in `Retry-After` before sending again. |
| 500 | [`internal_error`](https://hub.main-team.org/api/errors#internal_error) | Something failed on our side. Retry later, and quote `request_id` if it goes on. |

## Code samples

### curl

```bash
# $TOKEN: a short-lived token you minted with your API key and secret
curl -sS 'https://api.main-team.org/v1/api-account/validate-me' \
  -H "Authorization: Bearer $TOKEN"
```

### Node.js

```js
const token = process.env.TOKEN; // a short-lived token you minted with your API key and secret

const res = await fetch('https://api.main-team.org/v1/api-account/validate-me', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error.code}: ${body.error.message}`);
console.log(body);
```

### PHP

```php
<?php
$token = getenv('TOKEN'); // a short-lived token you minted with your API key and secret

$ch = curl_init('https://api.main-team.org/v1/api-account/validate-me');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $token,
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
if ($response === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$body = json_decode($response, true);
if ($status >= 400) {
    $error = $body['error'];
    throw new RuntimeException("$status {$error['code']}: {$error['message']}");
}
print_r($body);
```