The CLI authentication flow creates a session, opens a browser for the user to sign in, and polls until the session completes. grantiva auth login does all of this for you — this page documents the endpoints behind it.
Sessions are valid for 90 days from creation, but a session only stays useful until it is completed and polled once: the key is handed over exactly once and then cleared from the session record.
Create a session
No authentication. Returns the session id to embed in the browser login URL.
Response
Open https://api.grantiva.io/api/v1/auth/cli?session=<session_id> in the user’s browser. They sign in there with a password or a passkey.
Poll session status
No authentication — knowing the session id is the credential, so treat it as a secret.
Response
status is pending, active, or expired. A pending session past its expiry flips to expired on the next poll.
When the browser login completes, the next poll returns the key:
The api_key is returned once. The server clears it from the session as soon as it is read — a second poll returns "api_key": null with status: "active". Store it on first read.
gpat_ prefix) scoped to the user’s default organization, with full API access. It is named CLI session (<email>) and appears in the organization’s API key list. Revoke it there to sign the CLI out permanently.
Errors
Validate a key
Response
api_key_prefix is the first 8 characters of the key. 401 when the key is unknown, revoked, or expired.
See also
