Getting Started

Authentication

Moyo Suite authenticates the web app with email + password, optional two-factor authentication, and short-lived tokens — not a long-lived API key.

Programmatic, third-party API-key access is planned but intentionally not available yet — keys need to be stored hashed, scoped, rotated, and audited server-side first. The POST /api/v1/auth/login flow below is what the Moyo Suite frontend itself uses; there is no separate developer API-key program today.

Every endpoint on this page is prefixed with /api/v1 — e.g. POST /api/v1/auth/login, not POST /auth/login.

Logging in

1POST /api/v1/auth/login
2{
3  "email": "you@company.com",
4  "password": "••••••••"
5}
  • If the account has no 2FA enabled, this returns access_token and refresh_token (JWTs, token_type: "bearer") directly.
  • If the account has 2FA enabled, it instead returns requires_2fa: true plus a short-lived temp_token — see below.

Other ways in: a magic link (POST /api/v1/auth/magic-link → emailed one-time link → POST /api/v1/auth/magic-verify), or social/OAuth login.

Two-factor authentication

2FA is TOTP-based (Google Authenticator, Authy, etc.), not a stub:

1

Set up

POST /api/v1/auth/2fa/setup returns a base32 secret, an otpauth:// URI to render as a QR code, and one-time backup codes.

2

Confirm

POST /api/v1/auth/2fa/confirm with a 6-digit code from your authenticator app turns 2FA on.

3

Verify at login

After a login returns requires_2fa: true, call POST /api/v1/auth/2fa/verify with the temp_token and a 6-digit code to receive the real access_token/refresh_token. This endpoint is rate-limited to 5 attempts/minute.

You can disable 2FA (POST /api/v1/auth/2fa/disable, requires password + a valid code), check status (GET /api/v1/auth/2fa/status), or regenerate backup codes (POST /api/v1/auth/2fa/backup-codes).

How tokens are used

Once you’re authenticated, requests carry credentials one of two ways:

  • Authorization: Bearer <access_token> header, or
  • HttpOnly cookies the API sets on the login response — moyo_session and moyo_refresh, scoped to your organization’s whole domain for SSO across Moyo Suite subdomains.

The Moyo Suite web app itself doesn’t read those SSO cookies directly. Its frontend makes a server-to-server call to /api/v1/auth/login, then writes its own first-party accessToken/refreshToken cookies from the JSON response. If you’re calling the API directly (not through the Moyo Suite web app), the moyo_session/moyo_refresh cookies above are the ones that matter.

POST /api/v1/auth/refresh (with a body token or the moyo_refresh cookie) rotates both tokens before they expire.

refresh_tokens are long-lived credentials — never log them or expose them to client-side JavaScript. The cookie-based flow keeps them HttpOnly for exactly this reason.

Sessions

You can see and manage every device you’re signed in on:

EndpointWhat it does
GET /api/v1/auth/sessionsList active sessions
POST /api/v1/auth/sessions/revokeRevoke one session
POST /api/v1/auth/sessions/revoke-othersSign out every session except this one
POST /api/v1/auth/logout-allSign out everywhere

Signing up

POST /api/v1/auth/signup creates a brand-new organization and its first admin user in a single call (email, password, tenant_name, subdomain, initial_modules) — this is what powers Creating Your Organization. Joining an existing organization instead happens via a team invite; see Team & Permissions.