Skip to main content
Every /v1 request needs a credential. Send it as a bearer token:
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

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: The endpoints they list: 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.
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.
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. Request limits are in Rate limits.

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.