Guide

Authentication

The SwiftGoma API uses short-lived access tokens paired with longer-lived refresh tokens. Accounts can sign in with a password, a one-time email code, a passkey, or Google — and can optionally add TOTP-based two-factor authentication on top of any of them. Every endpoint mentioned on this page lives under https://api.swiftgoma.com/api/v1/auth.

Access and refresh tokens

A successful sign-in produces two tokens. The access token is short-lived and sent with every authenticated request. The refresh token lives much longer and is only used to obtain a new access token via POST /refresh-token once the access token expires. Neither token is ever returned in a way your client needs to parse manually on web — see below.

Web vs. mobile sessions

Browser and mobile clients receive their tokens differently, and every login and session endpoint behaves accordingly based on one header:

// Web (browser)
// Access & refresh tokens are set as httpOnly cookies automatically.
// Just send credentials on every request:
fetch(url, { credentials: "include" });

// Mobile
// Send this header on every request, and manage the tokens yourself:
fetch(url, { headers: { "x-client-type": "mobile" } });

Ways to sign in

All four methods converge on the same result — a session for web, or a token pair for mobile — and all four can be intercepted by a two-factor challenge if the account has TOTP enabled.

Password login

1. 1

   Send email and password

   POST /login/password with email and password.
2. 2

   Handle the result

   If the account doesn't have 2FA enabled, you get a session immediately. If it does, you get a pendingToken instead — see Two-factor authentication below.

Passwordless email code

1. 1

   Request a code

   POST /login/request-otp with just the email. The response is identical whether or not the address is registered, so this step never reveals account existence.
2. 2

   Verify the code

   The user receives a code by email. Submit it to POST /login/verify-otp along with the email.

Passkey

1. 1

   Get a challenge

   POST /passkey/login/options with the email returns a WebAuthn assertion challenge and a challengeId.
2. 2

   Resolve it with the browser

   Pass the challenge to navigator.credentials.get() in the browser.
3. 3

   Verify the assertion

   Send the browser's response and the challengeId to POST /passkey/login/verify.

Two-factor authentication

When an account has TOTP enabled, every login method above returns this instead of a session:

{
  "success": true,
  "data": {
    "requiresTotp": true,
    "pendingToken": "mfa_9f8e7d6c5b4a3210"
  }
}

Prompt the user for their 6-digit authenticator code (or an unused backup code), then finish with POST /login/totp, passing the pendingToken.

Turning it on

1. 1

   Start setup

   POST /totp/setup (authenticated) returns a secret and a QR code to scan into an authenticator app.
2. 2

   Confirm it

   POST /totp/confirm with the first 6-digit code turns 2FA on and returns a one-time set of backup codes — show these to the user immediately, they aren't retrievable later.

Password management

Session management

A signed-in user can inspect and manage their own active sessions:

Rate limits

Auth endpoints are grouped into tiers with different limits, tightest where the risk of abuse is highest:

Error handling

Errors share one shape:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Identifiants invalides."
  }
}