Authentication

The control-plane API (mikrom-api) accepts two interchangeable Bearer credentials on every protected endpoint. The machine-readable contract is at GET /v1/api-docs/openapi.json, with an interactive explorer at /v1/docs.

Choosing a credential

Credential	Best for	Lifetime
Session JWT	Interactive dashboard/CLI sessions	Configurable (ACCESS_TOKEN_TTL_SECS, default 24h)
Personal Access Token (PAT)	Scripts, CI, third-party integrations	Until revoked

Session flow

The CLI does this for you:

mikrom auth login --email <you@example.com> --password '<password>'

Under the hood:

1. POST /v1/auth/login with { "email", "password" } returns a user object, an access token, a refresh_token (mikrom_rt_...), and requires_2fa.
2. Send the JWT as Authorization: Bearer <token> on later calls.
3. When it expires, POST /v1/auth/refresh with the refresh token returns a fresh access token and a rotated refresh token; the old one is invalidated. Reusing a rotated refresh token revokes every session for the user (theft protection).
4. POST /v1/auth/logout revokes a refresh token explicitly.

Changing the password or deleting the account bumps an internal token version that immediately rejects all outstanding JWTs.

The CLI stores both tokens in ~/.config/mikrom/config.toml and refreshes automatically. Override with MIKROM_TOKEN / MIKROM_REFRESH_TOKEN.

Personal Access Tokens

mikrom pat create "ci-deployer"     # prints the token once
mikrom pat list
mikrom pat revoke <token-id>

Or over HTTP:

curl -X POST https://<api-host>/v1/auth/tokens \
  -H "Authorization: Bearer <jwt-or-pat>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-deployer" }'

• The plaintext token (mikrom_pat_...) is shown once at creation — store it in a secret manager.
• Only the last four characters are retained for display.
• Revoke independently: DELETE /v1/auth/tokens/{token_id}.
• Storage is a peppered HMAC of the token, so a database compromise alone cannot recover usable credentials.

Use a PAT the same way as a JWT:

curl https://<api-host>/v1/apps \
  -H "Authorization: Bearer mikrom_pat_xxxxxxxxxxxxxxxx"

To use a PAT with the CLI in CI, set MIKROM_TOKEN=mikrom_pat_....

Two-factor authentication

TOTP 2FA is available via POST /v1/auth/2fa/setup, /verify, and /disable. When 2FA is enabled, login returns requires_2fa: true and the second factor must be provided to complete the session.

Rate limits

Traffic is rate limited per IP and per tenant. When throttled you get 429 with a Retry-After header — back off for the indicated delay and retry.