API reference

API reference: Auth

Cloud Control authentication API: register, login, logout, me, MFA (setup/enable/verify/disable/status), password reset, and OIDC single sign-on start and callback.

The authentication surface. Most routes here are public (they are what you use before you have a session); MFA management requires a session.

POST/api/auth/registerPublic

Create a new organization and its Owner, and sign in.

Parameters

Name	In	Required	Description
`org`	body	yes	Organization name.
`name`	body	yes	Your name.
`email`	body	yes	Work email (globally unique today).
`password`	body	yes	At least 8 characters.

Example request

json

{ "org": "Acme", "name": "Ada Lovelace", "email": "ada.lovelace@example.com", "password": "correct horse" }

Example response

json

{ "ok": true }

Errors

Status	When
`400`	Missing/invalid org, name, email or a password under 8 chars.
`409`	An account with this email already exists.
`503`	Database unavailable.

POST/api/auth/loginPublic

Parameters

Name	In	Required	Description
`email`	body	yes	Account email.
`password`	body	yes	Account password.

Example request

json

{ "email": "ada.lovelace@example.com", "password": "correct horse battery" }

Example response

json

// No MFA:
{ "ok": true }
// MFA enabled:
{ "ok": true, "mfaRequired": true, "mfaToken": "…" }

Errors

Status	When
`400`	Missing email or password.
`401`	Email or password incorrect (identical for both).
`403`	The organization is suspended.
`429`	Locked after 5 failures; carries Retry-After.
`503`	Database unavailable.

POST/api/auth/logoutSession

Destroy the current session and clear the cookie.

Example response

json

{ "ok": true }

GET/api/auth/meSession or Bearer

Return the current user, including effective capabilities.

Example response

json

{ "user": { "id": 1, "orgId": 1, "name": "Ada Lovelace", "email": "ada.lovelace@example.com",
  "role": "Org Admin", "orgName": "Acme", "orgSlug": "acme",
  "isPlatformAdmin": false, "isOwner": true,
  "capabilities": ["read","mutate_infra","manage_cloud_accounts","manage_users_sso","manage_billing_transfer"] } }

Errors

Status	When
`401`	Not signed in / invalid token.

POST/api/auth/mfa/setupSession

Begin TOTP enrollment; returns a secret and an otpauth URL.

Example response

json

{ "secret": "BASE32…", "otpauthUrl": "otpauth://totp/CloudControl:…" }

Errors

Status	When
`401`	Not signed in.
`409`	MFA is already enabled — disable it first to re-enroll.

POST/api/auth/mfa/enableSession

Confirm a TOTP code to enable MFA; returns one-time recovery codes.

Parameters

Name	In	Required	Description
`code`	body	yes	Current 6-digit authenticator code.

Example request

json

{ "code": "123456" }

Example response

json

{ "ok": true, "recoveryCodes": ["…", "… (8 total)"] }

Errors

Status	When
`400`	Missing code, no pending secret, or the code didn't match.
`401`	Not signed in.
`409`	MFA is already enabled.

POST/api/auth/mfa/verifyPublic (MFA challenge)

Exchange a login MFA challenge token plus a code for a session.

Parameters

Name	In	Required	Description
`mfaToken`	body	yes	Single-use token from login.
`code`	body	yes	Authenticator or recovery code.

Example request

json

{ "mfaToken": "…", "code": "123456" }

Example response

json

{ "ok": true }

Errors

Status	When
`400`	Missing token or code.
`401`	Invalid/expired challenge or wrong code (identical message).
`429`	Locked after 5 wrong codes; carries Retry-After.

POST/api/auth/mfa/disableSession

Disable MFA, proving possession with a current authenticator or recovery code.

Parameters

Name	In	Required	Description
`code`	body	yes	Authenticator or recovery code.

Example response

json

{ "ok": true }

Errors

Status	When
`400`	Missing code, MFA not enabled, or the code didn't match.
`401`	Not signed in.

GET/api/auth/mfa/statusSession

Report whether MFA is enabled for the current user.

Example response

json

{ "enabled": true }

Errors

Status	When
`401`	Not signed in.

POST/api/auth/forgotPublic

Request a password-reset link. Enumeration-safe — the response is identical whether or not the email exists.

Parameters

Name	In	Required	Description
`email`	body	yes	Account email.

Example request

json

{ "email": "ada.lovelace@example.com" }

Example response

json

{ "ok": true }

Errors

Status	When
`400`	Malformed email.
`503`	Database unavailable.

POST/api/auth/resetPublic (reset token)

Set a new password with a single-use reset token; revokes all existing sessions.

Parameters

Name	In	Required	Description
`token`	body	yes	Single-use token from the reset link.
`password`	body	yes	New password, at least 8 characters.

Example request

json

{ "token": "…", "password": "new-password" }

Example response

json

{ "ok": true }

Errors

Status	When
`400`	Password under 8 chars, or an invalid/expired/used token (identical message).
`503`	Database unavailable.

POST/api/auth/oidc/startPublic

Begin SSO: match an email domain or org slug to an enabled OIDC config and return the IdP authorize URL.

Parameters

Name	In	Required	Description
`email`	body	no	Work email (its domain is matched).
`slug`	body	no	Organization slug (alternative to email).

Example request

json

{ "email": "user@acme.io" }

Example response

json

{ "ok": true, "authorizeUrl": "https://idp.example.com/authorize?…" }

Errors

Status	When
`400`	Neither email nor slug provided, or malformed email.
`404`	No enabled SSO for that domain or org (identical whether or not the org exists).
`503`	Database unavailable.

GET/api/auth/oidc/callbackPublic (IdP redirect)

OIDC redirect target. Exchanges the code, verifies the RS256 ID token against your JWKS, JIT-provisions new users with the org default role, and sets a session. Redirects the browser — not called directly.