> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockgence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Base URL, how to send your key and what each key can see.

## Base URL

```
https://app.blockgence.com/v1
```

Every API path hangs from `/v1`. If your organization has its own installation, use the URL you were given.

## Sending the key

Every `/v1` path requires an API key. Send it in either of these headers:

**Authorization** `string`

`Bearer bkg_live_…`. The standard form, used by most HTTP clients and by the MCP.

**X-API-Key** `string`

`bkg_live_…`, without a prefix. Equivalent to the previous one.

```bash curl theme={null}
curl "https://app.blockgence.com/v1/screening/0x098b716b8aaf21512996dc57eb0615e2383e2f96?chain=ethereum" \
  -H "Authorization: Bearer $BKG_KEY"
```

```python Python theme={null}
import os
import httpx

r = httpx.get(
    "https://app.blockgence.com/v1/screening/0x098b716b8aaf21512996dc57eb0615e2383e2f96",
    params={"chain": "ethereum"},
    headers={"Authorization": f"Bearer {os.environ['BKG_KEY']}"},
)
r.raise_for_status()
print(r.json())
```

```javascript JavaScript theme={null}
const r = await fetch(
  "https://app.blockgence.com/v1/screening/0x098b716b8aaf21512996dc57eb0615e2383e2f96?chain=ethereum",
  { headers: { Authorization: `Bearer ${process.env.BKG_KEY}` } },
);
if (!r.ok) throw new Error(`${r.status}: ${(await r.json()).detail}`);
console.log(await r.json());
```

> [!WARNING]
>
> Keep the key in an environment variable or a secrets manager, never in your code. How to create and revoke it:
> [API keys](https://docs.blockgence.com/en/get-started/api-keys.md).

## What each key can see

| Key | Acts as | Sees | Uses |
| - | - | - | - |
| Personal | Its owner | That person's cases and labels, the same as in the web app | The person's quota or, on `enterprise`, their organization's |
| Organization | The organization | The organization's cases and the ones it shares | The organization's quota |

A key of a person with the `viewer` role, or an organization key marked `read_only`, only reads: it can run every `GET`
and the `POST` requests that save nothing. See [Accounts and organizations](https://docs.blockgence.com/en/get-started/accounts-and-organizations.md#roles).

## Optional headers

**X-Case-Id** `string`

The case you are working on (`case_…`). Queries that carry it are recorded in the case's chain of custody, and labels
you add count only inside that case. If it names a case you cannot see, the response is `400` with
`error: "case_unavailable"` and the query is not run.

## Authentication responses

| Status | When |
| - | - |
| `401` | The key is missing, does not exist, was revoked, or the account (or organization) is deactivated. |
| `403` | The key cannot do that: it is read-only (`error: "read_only"`) or that resource is not in its `scopes` (`error: "key_scope"`). |
| `402` | The monthly quota is used up. See [Credits and limits](https://docs.blockgence.com/en/get-started/credits-and-limits.md). |
| `429` | You went over the rate limit. Wait the time given in `Retry-After`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.