> ## 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.

# Authentication

> Send a bearer credential with every request: an API key, or a sign-in access token.

Every `/v1` request needs a credential. Send it as a bearer token:

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

An API key is also accepted in the `x-api-key` header. A sign-in token is accepted only as a bearer token.

## Two kinds of credential

| | API key | Sign-in |
| - | - | - |
| Use it for | Scripts, CI jobs, servers, headless agents | A person at a terminal or in an agent |
| Looks like | `ic-live-...` | `ic-at-...` (access token) |
| Lifetime | Until it is revoked | Access token: 1 hour. Renewed with a refresh token for up to 30 days |
| Acts as | The workspace the key belongs to | The workspace of the signed-in account |
| How to get one | See [API keys](https://docs-agentic-id.icustomer.ai/api-keys.md) | `agentic-id login`, or `/agentic-id-login` in Claude Code |

Both draw on the wallet of the workspace they act as. To see which one a request used, call `GET /v1/workspace` and read `signed_in_as` (`api_key` or `account`).

## Sign-in

Sign-in is OAuth 2.1 authorization code with PKCE. From your side:

**1. Start it**

Run `agentic-id login` in a terminal, or type `/agentic-id-login` in Claude Code.

**2. Sign in in the browser**

Your browser opens the iCustomer sign-in page. If no browser opens, use the link the command prints. You have 5 minutes to finish.

**3. Go back to your tool**

When the page says you are signed in, the tool holds an access token and a refresh token. It renews the access token by itself. `agentic-id logout` ends the sign-in.

You never type a password, a code or a key into a chat or a terminal. Sign-in happens only in the browser.

### Build your own client

A client finds everything it needs from the discovery documents:

| Document | Path |
| - | - |
| Authorization server metadata | `/.well-known/oauth-authorization-server` |
| Protected resource metadata | `/.well-known/oauth-protected-resource` |

The endpoints they list:

| Endpoint | Path | Notes |
| - | - | - |
| Client registration | `POST /oauth/register` | Dynamic registration. Public clients only, no client secret. Send 1 to 10 `redirect_uris` |
| Authorization | `GET /oauth/authorize` | `response_type=code`, `code_challenge_method=S256`, scope `agentic-id` |
| Token | `POST /oauth/token` | Grants: `authorization_code`, `refresh_token` |
| Revocation | `POST /oauth/revoke` | Ends a token |

Rules to know:

* **PKCE is required.** `S256` is the only challenge method.
* **Redirects are loopback by default.** Register an `http://127.0.0.1/...` redirect. The port may differ when the redirect comes back.
* **Refresh tokens rotate.** Each renewal returns a new refresh token. Presenting an old one a second time ends the whole sign-in, so renew from one place at a time.
* **Access tokens last 1 hour.** Refresh tokens last 30 days.

> [!NOTE]
>
> If `/.well-known/oauth-authorization-server` answers 404, that server does not offer sign-in. Use an API key.

## When a credential is refused

Errors are problem details (`application/problem+json`) with a stable `code`.

| Status | `code` | When | What to do |
| - | - | - | - |
| 401 | `auth.invalid_key` | No credential was sent, or the key or token is wrong or revoked | Send a valid key or sign in again |
| 401 | `auth.token_expired` | The sign-in access token has expired | Refresh the token, or sign in again |
| 429 | `rate_limited` | Too many refused credentials from your address in one minute | Wait for the number of seconds in the `Retry-After` header |

```json theme={null}
{
  "type": "https://docs.agentic-id.icustomer.ai/errors/auth.invalid_key",
  "title": "Unauthorized",
  "status": 401,
  "code": "auth.invalid_key",
  "detail": "Send an Agentic ID API key as \"Authorization: Bearer ic-...\" or \"x-api-key\".",
  "request_id": "0d1c7a0e-52f3-4b0a-8f7e-3b6a1c9d2e44"
}
```

When sign-in is on, a 401 also carries a `WWW-Authenticate` header that points at the protected resource metadata, so a client knows where to sign in.

A missing credential and a wrong one both return `auth.invalid_key`. The full list of codes is in [Errors](https://docs-agentic-id.icustomer.ai/errors.md). Request limits are in [Rate limits](https://docs-agentic-id.icustomer.ai/rate-limits.md).

## What a credential can read

Contact values such as emails are returned masked by the API today, whichever credential you use. See [Data and privacy](https://docs-agentic-id.icustomer.ai/data-privacy.md).


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