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

# API keys

> What a key looks like, how to get one, and how to keep it safe.

An API key lets a script, a CI job or a headless agent call Agentic ID without a person signing in. A key belongs to one workspace and draws on that workspace's credit wallet.

## Format

| Part | Value |
| - | - |
| Prefix | `ic-live-` for production keys. `ic-dev-` for keys from a non-production server |
| Secret | 32 URL-safe characters after the prefix |
| Example | `ic-live-...` |

Every key starts with `ic-`. The prefix tells you at a glance which kind of server issued it.

## Get a key

Keys are issued by the Agentic ID team today. There is no self-serve page to create one.

**1. Ask your Agentic ID contact**

Say which workspace the key is for and what you will use it for, so the key can be named.

**2. Store the secret at once**

The secret is shown once, when the key is created. Agentic ID keeps only a hash of it and a short prefix, so it cannot be shown again. If you lose it, ask for a new key.

**3. Check it works**

```bash theme={null}
curl -s "https://YOUR_AGENTIC_ID_HOST/v1/workspace" \
  -H "Authorization: Bearer $AGENTIC_ID_API_KEY"
```

The answer names the workspace and shows `"signed_in_as": "api_key"`.

If you are a person working at a terminal or in Claude Code, you do not need a key. [Sign in](https://docs-agentic-id.icustomer.ai/authentication.md) with your iCustomer account.

## Use a key

Send it as a bearer token, or in the `x-api-key` header.

```bash Authorization header theme={null}
curl -s "https://YOUR_AGENTIC_ID_HOST/v1/credits" \
  -H "Authorization: Bearer $AGENTIC_ID_API_KEY"
```

```bash x-api-key header theme={null}
curl -s "https://YOUR_AGENTIC_ID_HOST/v1/credits" \
  -H "x-api-key: $AGENTIC_ID_API_KEY"
```

The CLI and the MCP server read the key from the `AGENTIC_ID_API_KEY` environment variable, or from the file named in `AGENTIC_ID_API_KEY_FILE`. The Claude Code plugin takes it as an option and keeps it in your system keychain.

## Scopes

A key carries a list of scopes. `GET /v1/workspace` returns them in `scopes`.

| Scope | Meaning |
| - | - |
| `pii:read` | The key may read contact values unmasked |

> [!NOTE]
>
> The API returns contact values such as emails masked today, with or without `pii:read`.

## Revoke or replace a key

Ask your Agentic ID contact to revoke a key. Give the key's short prefix (the first characters, for example `ic-live-a1B2c3D`), never the whole secret. A revoked key stops working within 30 seconds. After that, requests with it return `401 auth.invalid_key`.

To rotate a key: get a new one, switch your systems to it, then have the old one revoked.

## Keep keys safe

> [!WARNING]
>
> A key is a bearer credential. Anyone who holds it can spend your workspace's credits.

* Keep keys in a secret manager, an environment variable or your system keychain.
* Never put a key in a URL, a prompt, a chat message, a command line or a committed file.
* Never paste a key into a conversation with an agent. An agent should never ask for one.
* If you keep a key in a file, keep the file outside any repository and readable by you only.
* Use one key per system, so you can revoke one without stopping the others.
* Set `max_credits` on paid calls, so a leaked or looping caller is capped per call. See [Credits](https://docs-agentic-id.icustomer.ai/credits.md).
* If a key may have leaked, have it revoked first and investigate after.


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