/v1 request needs a credential. Send it as a bearer token:
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.Build your own client
A client finds everything it needs from the discovery documents:
The endpoints they list:
Rules to know:
- PKCE is required.
S256is 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.
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.

