Reference / Reference

Authentication

Three kinds of principal, three mechanisms, and the one that cannot step up.

Four principal types, three authentication mechanisms.

principal.type is a policy field, so a rule can apply to automation but not to people, or the reverse.

#Human sessions

httpCopy
POST /v1/auth/signup     # creates an organization and its first owner, one transaction
POST /v1/auth/login
POST /v1/auth/mfa/verify
POST /v1/auth/step-up
GET  /v1/auth/session
POST /v1/auth/logout

Login returns a session token, or an MFA challenge to complete first.

bashCopy
curl -s $CP/v1/auth/session -H "Authorization: Bearer $SESSION"

Returns the current session, its scope, and the effective permissions — the authoritative answer to "what can I do", and what the console uses to decide what to render.

Signup creating the organization and its first owner in one transaction means there is no window in which an organization exists with nobody able to administer it.

#Step-up

httpCopy
POST /v1/auth/step-up
{ "password": "…" }

Thirteen permissions require a fresh re-authentication at the moment of use, regardless of session age. Without a current step-up they return 403 STEP_UP_REQUIRED.

A twelve-hour session is a reasonable credential for reading dashboards and not for revoking a production agent. → Step-up

#CLI

bashCopy
veefore login

Sign-in happens in the browser, never in the terminal. The CLI opens the console, you sign in there (password, MFA or SSO, exactly as for the console) and approve the terminal. The CLI receives a session token over a loopback redirect protected with PKCE (S256), so the terminal never sees your password.

Only the session token is stored, in ~/.veefore/credentials.json at mode 0600. Revoke it from your profile in the console like any other session.

veefore logout ends the session on the server as well as removing the stored token. Signing out of the console asks whether to also sign out of the Veefore CLI on your devices, ticked by default; that ends every terminal session you approved through browser sign-in. A terminal cannot be told the moment that happens, so the next command there reports that you were signed out, removes the stored token and asks you to sign in again. Sessions signed in with VEEFORE_EMAIL and VEEFORE_PASSWORD, as in CI, are not affected. The CLI connects to Veefore by itself. For a self-hosted Veefore, add --control-plane https://veefore.your-company.com the first time; later commands reuse it.

For CI, where nobody can open a browser, prefer an API key. If a pipeline must sign in as a user, set the credentials in the environment and the CLI uses them without prompting:

bashCopy
VEEFORE_EMAIL=ci@example.com VEEFORE_PASSWORD=… veefore login

#API keys

httpCopy
Authorization: Bearer aos_sk_…

For a service or a pipeline. Scoped to a role, optionally to a workspace, with an expiry up to 730 days.

bashCopy
curl -X POST $CP/v1/api-keys \
  -H "Authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{ "name": "ci-policy-gate", "role_id": "role_01JAV…", "workspace_id": "wsp_01JAV…", "expires_in_days": 90 }'

Pick the smallest role. Never OWNER — it holds organization:delete, and a CI secret is readable by every build step. → API keys

#Agent authentication

Agents authenticate at the gateway, with a signed assertion. No passwords, no API keys, no human credentials.

httpCopy
POST /gateway/v1/token
{
  "agent_id": "agt_01JAV…",
  "assertion": "eyJ0eXAiOiJhZ2VudG9zLWFzc2VydGlvbit…",
  "sdk": { "name": "@veefore/sdk", "version": "1.0.0", "runtime": "node20" }
}

jsonCopy
{
  "data": {
    "token": "aos_at_…",
    "token_type": "Bearer",
    "expires_in": 900,
    "expires_at": "2026-10-03T12:53:04.000Z",
    "agent_id": "agt_01JAV…",
    "environment_id": "env_01JAV…",
    "organization_id": "org_01JAV…"
  }
}

Or POST /gateway/v1/handshake, which also returns the authorized tool list, the capabilities, the enforcement mode and the passport version.

#What is checked

bashCopy
curl -s https://gateway.veefore.example.com/.well-known/veefore-platform-key

#No refresh token

Full wire format: Sign your own assertion.

#Comparison

#The published values

bashCopy
curl -s https://gateway.veefore.example.com/.well-known/veefore-platform-key

The platform public key, its id, and the gateway audience. No authentication, cached for five minutes.

#Related