Skip to main content
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.
The issued key is a personal access token (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

​
Headers

​
Response

api_key_prefix is the first 8 characters of the key. 401 when the key is unknown, revoked, or expired.

​
See also