3. Authentication

Session login, identity, password changes, Platform Admin tenant switching, and long-lived API tokens for non-interactive callers (CI, CSI drivers, monitoring collectors).

Endpoint Summary

POST /api/v1/auth/change-password

Change own password

Change the signed-in user’s own password, verifying the current one. Acts on the caller’s identity from the token. Not available for accounts managed by an external identity provider. For administrative resets, use PATCH /tenants/{tenant_id}/users/{user_id}.

Authentication: required (PasswordLogin or BearerJWT).

Request Body (application/json, required)

Schema: ChangePasswordRequest

Self-service change-password payload. Carries no user/tenant id - the caller comes from the token.

Example

{
   "current_password" : "Curr3nt!pw",
   "new_password" : "N3w!password"
}

Responses

POST /api/v1/auth/login

Login

Authenticate with username and password and receive a JWT access and refresh token pair. The username names the tenant it belongs to, <tenant-name>/<user> (for example fintech/alice); an unprefixed name belongs to the platform tenant.

Authentication: not required.

Request Body (application/x-www-form-urlencoded, required)

Schema: LoginForm

Credentials for POST /auth/login, where the user name carries the tenant.

Any other form field an OAuth2 client sends is accepted and ignored.

Example

{
   "password" : "Secret1!",
   "username" : "admin"
}

Responses

Response Body (200, TokenResponse)

GET /api/v1/auth/me

Current user identity

Returns the authenticated user’s identity, the effective tenant, and what the caller may do there: the roles they hold and every permission those roles grant, as resource:action. The tenant is resolved from the tid claim in the JWT, and roles and permissions are read from that tenant’s policy - the same one the server enforces against. While a tenant switch is active, tenant_id is the tenant being acted in, the access reported is the one held there, and the delegation fields describe the switch - enough for the client to show an “acting as” banner.

Authentication: required (PasswordLogin or BearerJWT).

Responses

Response Body (200, MeResponse)

Example

{
   "is_delegated" : false,
   "is_platform_admin" : false,
   "permissions" : [
      "tenants:view",
      "volumes:list",
      "volumes:view",
      "users:list",
      "users:view",
      "users:update",
      "users:delete",
      "observability:list",
      "observability:view",
      "roles:view",
      "roles:update"
   ],
   "roles" : [
      "admin"
   ],
   "tenant_id" : "123e4567-e89b-12d3-a456-426614174000",
   "user_id" : "123e4567-e89b-12d3-a456-426614174000"
}

POST /api/v1/auth/refresh

Refresh tokens

Exchange a valid refresh token for a new JWT access and refresh token pair.

Authentication: not required.

Request Body (application/x-www-form-urlencoded, required)

Schema: Body_refresh_api_v1_auth_refresh_post

Responses

Response Body (200, TokenResponse)

POST /api/v1/auth/tenant-switch

Switch into a tenant (Platform Admin only)

Exchange your current access token for a short-lived token scoped to the requested tenant. Only callers with tenants:switch can use this endpoint. The delegated token includes tid (target tenant) and act (original caller), has no refresh token, and does not change stored RBAC policy.

In Swagger UI, paste the returned access_token into BearerJWT; logging out of it ends the switch.

Authentication: required (PasswordLogin or BearerJWT).

Request Body (application/json, required)

Schema: TenantSwitchRequest

Platform Admin request to exchange the current access token for a target-tenant one.

Example

{
   "tenant_id" : "e97b94d6-9cc1-4325-a267-1064ae538ccd",
   "ttl_minutes" : 60
}

Responses

Response Body (200, DelegatedTokenResponse)

GET /api/v1/auth/tokens

List your API tokens

Return the caller’s own API tokens, newest first. Carries no secret and no digest - the token itself is unrecoverable after issuance. Revoked and expired tokens stay listed, so a revocation stays visible; neither holds a slot or its name any more.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, ApiTokenListResponse)

POST /api/v1/auth/tokens

Issue an API token

Issue a long-lived credential for a non-interactive caller - a CLI, a CSI driver, a CI job, a monitoring collector. The token authenticates as you, carrying the roles you hold now and never exceeding what you hold at the time of each request.

The token is returned once, in this response, and cannot be retrieved again.

Requires an interactive session: an API token cannot issue another, and a tenant switch cannot leave one behind.

Authentication: required (PasswordLogin or BearerJWT).

Request Body (application/json, required)

Schema: ApiTokenCreateRequest

Request to issue a long-lived API token for the caller.

Example

{
   "description" : "Nightly backup runner",
   "expires_in_days" : 90,
   "name" : "nightly-backup@ci-runner-04"
}

Responses

Response Body (201, ApiTokenCreatedResponse)

GET /api/v1/auth/tokens/{token_id}

Read one of your API tokens

Metadata for one token you own. A token belonging to another user answers the same as one that does not exist, so the endpoint cannot be used to probe another inventory.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses

Response Body (200, ApiTokenResponse)

DELETE /api/v1/auth/tokens/{token_id}

Revoke an API token

Revoke one token you own. It stops authenticating on the very next request - the record is read on every request, so there is no cache to wait out.

Idempotent: revoking an already-revoked token succeeds and keeps the first revocation on record. The record is retained as a tombstone, so a later use of the token reports as revoked rather than as unknown.

Unlike issuance, this is open to a token-authenticated caller, so a compromised client can always burn its own credential.

Authentication: required (PasswordLogin or BearerJWT).

Parameters

Responses