API keys, OAuth apps and the CLI

Everything you do in Velrix goes through its HTTP API, at https://<realm>/api/<capability>/<event>. Three ways let something other than your browser call it:

• an API key, for a script, a CI job or an AI agent;
• an OAuth app, which asks each person what it may do for them;
• the velrix command, which signs you in from your own machine.

The API reference and the Terraform, Ansible and MCP pages are in your realm’s Docs window (The API reference in your realm).

Scopes

All three ask for scopes: what the credential may call.

Mail is the email capability, but email alone is the sign-in scope for your address. So ask for mail as email:* or email.read.

A credential never reaches more than you do yourself. Without act_in_scopes it acts only in your own scope, even if you are in organisations.

API keys

Open API keys (on your account page, or an organisation’s page for its keys) and choose New key.

1. Give it a Name you will know it by, such as CI deploy.
2. Choose how many days it lives, at most 365. A key can’t be extended: you make a new one.
3. Tick its Scopes, and Read-only if it only needs to read. On a personal key, Act in your organisations lets it work in your organisations.
4. Copy the secret. It is shown once; only a hash of it is kept.

Send the secret as a bearer token, Authorization: Bearer <secret>, or use it as the password where a login asks for one, such as podman login for the registry.

An organisation’s key acts as the person who made it, only within that organisation, and only for what was ticked.

Keeping keys small

• Use shows each first use from an address or for an action.
• Least privilege judges the key by what it really did: never used, not used lately, only reads used, or used a few of its actions. Make a narrower key makes one with only what was used.
• Revoke stops a key at once.

A key made with a whole capability follows new releases: actions a release adds to it are granted, and actions it removes go. A key made with single actions never widens. The key’s page says when a release changed it.

OAuth apps

Register an app

For a web app, a CLI or an assistant that signs people in to your realm: open Connected apps and choose Register an app.

• Redirect URIs are matched exactly: https://, or http://127.0.0.1 on any port for an app on the person’s own machine. None, for a CLI that only signs in with a device code.
• Confidential for a server that can keep a secret; apps on people’s machines are public and prove themselves with PKCE.
• Scopes are the most it may ask for.

At https://<realm>/.well-known/openid-configuration an app finds everything it needs: the realm is an OAuth 2.1 and OpenID Connect server.

When an app asks you

An app sends you to the realm’s sign-in page. Once you’re signed in, a card names the app, who registered it, where it returns to and what it asks for. Untick anything you don’t want it to have, then Allow or Deny. The realm remembers what you allowed, so the next sign-in asks only for something new.

Connected apps on your account page lists the apps you allowed. Revoke ends every token the app holds for you at once.

The velrix command

The velrix command signs you in from any machine, and calls the API with your rights.

velrix login https://cloud.example.se                 # opens the browser
velrix login https://cloud.example.se --device        # no browser here: a code to type elsewhere
velrix login https://cloud.example.se --scope "sites databases email:* act_in_scopes"
velrix api sites:list
velrix api sites:create '{"scope":"org:acme","name":"shop"}'

A plain sign-in can’t call anything: add what you need with --scope, and the card in the browser lets you untick any of it. The command renews its own tokens, and velrix logout ends the session at the realm. With --profile you keep one sign-in per realm.

velrix access gives you a credential for an app behind Velrix Access, for git or a TCP tunnel; the CLI reference lists every command.