CLI authentication

The CLI authenticates against your organization's customer identity (CIAM) sign-in authority using the OAuth 2.0 device-code flow: xmatix login prints a verification URL and a short code, you complete sign-in in any browser — including on another machine — and the CLI receives tokens for the account you signed in as. Every subsequent command acquires a token silently from the cache and calls the API as that user, so the CLI's reach is always exactly the signed-in user's permissions.

xmatix login --tenant <tenant> \
  --api-base-url <api-url> --authority <authority-url> --client-id <client-id>

xmatix whoami       # prints the signed-in user and tenant
xmatix logout       # clears cached accounts for the workspace's tenant

The four login flags are needed once — they persist into the workspace config — after which a bare xmatix login re-runs the device-code flow with the stored settings whenever a session expires.

The token cache

Tokens are cached per tenant under ~/.xmatix/tokens/<tenant> in your home directory — not in the repository — and the cache file is encrypted with the operating system's native secure storage: the keychain on macOS, DPAPI on Windows, and the keyring/secret service on Linux. Silent acquisition refreshes tokens automatically; when a refresh is no longer possible (expiry, revocation, a password change), commands fail with a message telling you to run xmatix login again. xmatix logout removes all cached accounts for the tenant.

Configuration

.xmatix/config.json carries the tenant-scoped settings every command needs. It is created by xmatix init and populated by the first full xmatix login:

{
  "tenant": "<tenant>",
  "apiBaseUrl": "<api-url>",
  "authority": "<authority-url>",
  "clientId": "<client-id>",
  "scopes": "",
  "apiVersion": "v1"
}

Setting	Meaning
`tenant`	Your tenant slug — it namespaces the token cache
`apiBaseUrl`	The base URL of your organization's xMatix API
`authority`	Your organization's sign-in authority URL
`clientId`	The registered OAuth client id of the CLI application
`scopes`	Space-separated OAuth scopes; when empty, defaults to `{apiBaseUrl}/.default`
`apiVersion`	The API version segment used in routes (`v1`)

The file contains no secrets — committing it is how a whole team shares one working setup. Your administrator supplies the values; xmatix doctor verifies all of them plus a live token and an API round-trip.

Non-interactive use

Only the device-code flow is implemented today — there is no service-principal or client-credentials sign-in yet. For CI this means a job cannot mint a session from environment variables; the working pattern is a persistent, access-controlled runner on which xmatix login was completed once, after which silent acquisition keeps the cache fresh across jobs. The CI recipes page is written around this constraint, and non-interactive sign-in is planned.

Common questions

How do I work against two tenants?

One workspace per tenant. The config file binds a workspace to a single tenant, and the token cache is namespaced by tenant slug — so two checkouts (or two repositories) each with their own .xmatix/config.json coexist cleanly on one machine, each signing in and caching independently.

Does the CLI ever see or store my password?

No. The device-code flow hands authentication entirely to your organization's sign-in page in the browser — the same page, policies and factors as signing in to the product. The CLI receives only the resulting tokens, and stores them encrypted by the OS credential store.

Because the CLI executes with the signed-in user's permissions and the platform records who did what. A shared account erases that audit trail and usually holds broader permissions than any one person needs. Individual sign-in costs nothing — the config is shared through git; only the sign-in itself is per person.