Docs/Account/API/Authentication

Authentication API

Complete reference for all authentication endpoints. These endpoints handle user registration, login, token management, MFA verification, and password flows.

Base URL: https://id.vyntech.com.au/api/v1 — All paths below are relative to this base. Endpoints marked 🔒 require a valid access token in the Authorization: Bearer <token> header.

Register

Creates a new user within a tenant. Validates the password against the tenant's password policy, sends a verification email, and returns tokens so the user is authenticated immediately.

POST/api/v1/auth/registerPublic

Create a new user account and receive authentication tokens.

curl -X POST https://id.vyntech.com.au/api/v1/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": "jane@acme-corp.com", "password": "SecureP@ss2024!", "display_name": "Jane Smith", "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M" }'

Request Body

{
  "email": "jane@acme-corp.com",
  "password": "SecureP@ss2024!",
  "display_name": "Jane Smith",
  "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M"
}

Login

Authenticates a user with email and password. Returns tokens on success, or indicates that MFA verification or a risk challenge is required. The risk engine evaluates every login attempt automatically.

POST/api/v1/auth/loginPublic

Authenticate a user and receive tokens (or MFA/challenge requirement).

curl -X POST https://id.vyntech.com.au/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{ "email": "jane@acme-corp.com", "password": "SecureP@ss2024!", "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M" }'

Request Body

{
  "email": "jane@acme-corp.com",
  "password": "SecureP@ss2024!",
  "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M"
}

Verify MFA

Completes authentication when MFA is required. Submit the TOTP code from the user's authenticator app along with the mfa_token received from the login response. The MFA token is valid for 5 minutes.

POST/api/v1/auth/verify-mfaPublic

Complete MFA verification with a TOTP code.

curl -X POST https://id.vyntech.com.au/api/v1/auth/verify-mfa \ -H "Content-Type: application/json" \ -d '{ "mfa_token": "mfa_01H8NXYZ...", "code": "482913" }'

Request Body

{
  "mfa_token": "mfa_01H8NXYZ...",
  "code": "482913"
}

Refresh Token

Exchanges a valid refresh token for a new access token and refresh token pair. Refresh tokens are single-use — the old token is invalidated immediately (rotation). If a refresh token is used twice, the entire session is revoked.

POST/api/v1/auth/refreshPublic

Exchange a refresh token for new access and refresh tokens.

curl -X POST https://id.vyntech.com.au/api/v1/auth/refresh \ -H "Content-Type: application/json" \ -d '{ "refresh_token": "ref_01H8MWXY7A9B3C5D..." }'

Request Body

{
  "refresh_token": "ref_01H8MWXY7A9B3C5D..."
}

Logout

Revokes the current session and invalidates the refresh token. The access token will remain valid until it expires (max 15 minutes), so for immediate revocation, also remove the token from your client storage.

POST/api/v1/auth/logout🔒 Auth

Revoke the current session and refresh token.

curl -X POST https://id.vyntech.com.au/api/v1/auth/logout \ -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..."

Change Password

Changes the authenticated user's password. Requires the current password for verification. The new password is validated against the tenant's password policy. All other sessions for this user are revoked on success.

POST/api/v1/auth/change-password🔒 Auth

Change the current user's password (requires authentication).

curl -X POST https://id.vyntech.com.au/api/v1/auth/change-password \ -H "Authorization: Bearer eyJhbGciOiJFZERTQSIs..." \ -H "Content-Type: application/json" \ -d '{ "current_password": "SecureP@ss2024!", "new_password": "EvenStr0nger#2025" }'

Request Body

{
  "current_password": "SecureP@ss2024!",
  "new_password": "EvenStr0nger#2025"
}

Forgot Password

Initiates the password reset flow by sending a reset link to the user's email. Always returns 200 regardless of whether the email exists (prevents user enumeration). The reset token is valid for 1 hour.

POST/api/v1/auth/forgot-passwordPublic

Request a password reset email.

curl -X POST https://id.vyntech.com.au/api/v1/auth/forgot-password \ -H "Content-Type: application/json" \ -d '{ "email": "jane@acme-corp.com", "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M" }'

Request Body

{
  "email": "jane@acme-corp.com",
  "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M"
}

Reset Password

Completes the password reset using the token from the email link. Validates the new password against the tenant's policy and revokes all existing sessions for the user.

POST/api/v1/auth/reset-passwordPublic

Set a new password using a reset token from the email.

curl -X POST https://id.vyntech.com.au/api/v1/auth/reset-password \ -H "Content-Type: application/json" \ -d '{ "token": "rst_01H8QWER5T7Y9U1I...", "new_password": "MyNewSecure#Pass1" }'

Request Body

{
  "token": "rst_01H8QWER5T7Y9U1I...",
  "new_password": "MyNewSecure#Pass1"
}

Verify Email

Confirms the user's email address using the token from the verification email sent during registration. The token is valid for 24 hours.

POST/api/v1/auth/verify-emailPublic

Verify a user's email address with the token from the verification email.

curl -X POST https://id.vyntech.com.au/api/v1/auth/verify-email \ -H "Content-Type: application/json" \ -d '{"token": "evf_01H8ASDF3G5H7J9K..."}'

Request Body

{
  "token": "evf_01H8ASDF3G5H7J9K..."
}

Resend Verification Email

Sends a new email verification link if the original expired. Rate-limited to 3 requests per hour per user. Returns 200 regardless of whether the email exists.

POST/api/v1/auth/resend-verificationPublic

Send a new email verification link.

curl -X POST https://id.vyntech.com.au/api/v1/auth/resend-verification \ -H "Content-Type: application/json" \ -d '{ "email": "jane@acme-corp.com", "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M" }'

Request Body

{
  "email": "jane@acme-corp.com",
  "tenant_id": "tnt_01H7ABCD9E8F4G2H1J3K5L7M"
}

What's Next

Users API →

List, get, update, and delete users. Manage user roles and profile data.

Sessions API →

List active sessions, revoke individual sessions, or revoke all.

MFA Guide →

Set up TOTP MFA, manage recovery codes, and configure enforcement.

Authentication Flows →

Visual diagrams of login, registration, MFA, and risk challenge flows.