# Account

Check what a key can do before you rely on it. `GET /v1/account` is free and is the quickest way to confirm that a key works, which mode it is in, which scopes it has and how many credits the workspace has left.

## GET /v1/account

Inspect key permissions and available credits.

- **Scope:** `account:read`
- **Cost:** Free. Counts towards the per-minute valuation rate limit.
- **Rate limit:** valuations bucket, default 60 requests per minute. See [limits](/docs/concepts/limits).

### Response

`application/json`, a `Account`: The workspace and API key that made the call. Errors return a [Problem](/docs/reference/valuations#the-problem-object) as `application/problem+json`.

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Always `account`. |
| `organization` | object | The workspace that owns the key. |
| `organization.id` **required** | string | Workspace ID (`org_…`). Pattern `^org_[A-Za-z0-9]+$`. |
| `organization.name` **required** | string | Workspace name. |
| `key` | object | The API key that made this call. |
| `key.id` **required** | string | Key ID (`key_…`). Safe to log; it is not the secret. Pattern `^key_[A-Za-z0-9]+$`. |
| `key.mode` **required** | string | `test` (simulated, free) or `live`. One of `test`, `live`. |
| `key.scopes` **required** | array | Scopes granted to the key. |
| `credits_remaining` | integer | Valuation credits available to the workspace now. Minimum 0. |
| `allowed_countries` | array | Markets this key can value, as the ISO codes requests use in `country` (for example `DK`, `GB`, `DE`): the workspace's markets narrowed by the key's own allowed countries. When neither restricts the markets, every market is listed; the list is empty only when the key's markets and the workspace's do not overlap. |
| `rate_limit_per_minute` | integer | Requests allowed per minute for the workspace in the valuations bucket, and separately in the vehicles bucket (default 60 each). Catalogue requests have their own limit. Minimum 1. |
| `notes` | [Note](/docs/notices#notes) array | Always empty for account results. |
| `attributions` | [Attribution](/docs/notices#attributions) array | Always empty for account results. |

### Response headers

| Header | Description |
| --- | --- |
| `X-Request-Id` | The HTTP request ID, on every response. Use it to correlate one HTTP exchange in proxy and application logs; it echoes a valid X-Request-Id you send. It is not the valuation ID. |

### Errors

| Code | HTTP | Retryable | Meaning |
| --- | --- | --- | --- |
| [`unauthenticated`](/docs/errors#unauthenticated) | 401 | No | Supply an API key as a Bearer token. |
| [`invalid_api_key`](/docs/errors#invalid_api_key) | 401 | No | Supply a valid AutoUncle Data Services API key. |
| [`key_revoked`](/docs/errors#key_revoked) | 401 | No | This key has expired or been revoked. Create a new key. |
| [`insufficient_scope`](/docs/errors#insufficient_scope) | 403 | No | Use a key with the required scope. |
| [`organization_pending`](/docs/errors#organization_pending) | 403 | No | This workspace is waiting for AutoUncle to approve it. |
| [`organization_suspended`](/docs/errors#organization_suspended) | 403 | No | This organization is inactive. Contact support. |
| [`rate_limited`](/docs/errors#rate_limited) | 429 | Yes | The request rate limit was reached. Retry after the current minute. |

### Examples

**curl**

```bash
curl https://data-services.autouncle.com/v1/account \
  -H "Authorization: Bearer $AUTOUNCLE_API_KEY"
```

**Ruby**

```ruby
require "json"
require "net/http"

uri = URI("https://data-services.autouncle.com/v1/account")
request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer #{ENV.fetch("AUTOUNCLE_API_KEY")}"
response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.pretty_generate(JSON.parse(response.body))
```

**Python**

```python
import json
import os

import requests

response = requests.get(
    "https://data-services.autouncle.com/v1/account",
    headers={
        "Authorization": f"Bearer {os.environ['AUTOUNCLE_API_KEY']}",
    },
    timeout=30,
)
print(json.dumps(response.json(), indent=2))
```

**JavaScript**

```javascript
const response = await fetch("https://data-services.autouncle.com/v1/account", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.AUTOUNCLE_API_KEY}`,
  },
});
console.log(JSON.stringify(await response.json(), null, 2));
```

## Example response

```json
{
  "object": "account",
  "organization": { "id": "org_99ef3a8e2984f38e0b27c543", "name": "Docs Check Motors" },
  "key": {
    "id": "key_8ac1e502811e8e39937d1b21",
    "mode": "test",
    "scopes": ["valuations:write", "valuations:read", "catalogue:read", "account:read"]
  },
  "credits_remaining": 0,
  "allowed_countries": ["DK", "SE", "DE", "IT", "ES", "AT", "PT", "PL", "FI", "RO", "CH", "GB", "NL", "FR"],
  "rate_limit_per_minute": 60,
  "notes": [],
  "attributions": []
}
```

## Market codes in allowed_countries

`allowed_countries` lists the markets **this key** can value, as ISO codes, the same codes you send as `country` (`DK`, `GB`, `DE` and so on). It is the workspace's markets narrowed by the key's own allowed countries, if it has any. When neither restricts the markets, it lists every market. It is empty only when the key's allowed countries and the workspace's markets do not overlap. Compare it directly with the `country` you send. [Markets](/docs/concepts/markets) lists every market.

## Use it as a health check

Call it when your service starts, and alert when it fails. A `401` means the configured key is wrong or revoked, `403 insufficient_scope` means the key lacks `account:read`, and `403 organization_suspended` means the workspace is inactive. None of these consume credits.

Usage per key, request logs and the credit ledger are in the console under **Usage**, **Request logs** and **Billing**. The API does not expose them in this version.