Skip to main content
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

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

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 with your iCustomer account.

Use a key

Send it as a bearer token, or in the x-api-key header.
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.
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

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.
  • If a key may have leaked, have it revoked first and investigate after.