Authentication

Learn how to authenticate with the Mployr API using JWT tokens.

Overview

The Mployr API uses JWT (JSON Web Token) Bearer authentication. To make authenticated requests, you need to:

Obtain an access token by calling the login endpoint
Include the token in the Authorization header
Handle token expiration and refresh as needed

Getting an Access Token

To obtain an access token, send a POST request to the login endpoint with your email and password:

curl -X POST https://api.mployr.com.au/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response

A successful login returns the access token along with user information:

{
  "success": true,
  "data": {
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "user@example.com"
    }
  }
}

Token Expiration

Access tokens expire after 24 hours (86400 seconds). You'll need to re-authenticate or implement token refresh to continue making requests.

Using the Access Token

Include the token in the Authorization header for all authenticated requests:

authenticated-request.sh

curl https://api.mployr.com.au/v1/people \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9..."

Authorization Header Format

Authorization: Bearer <your-access-token>

Two-Factor Authentication

The API supports TOTP-based two-factor authentication for enhanced security. Users can enable 2FA through the API or UI.

Setting Up 2FA

2fa-setup.sh

# Check 2FA status
curl https://api.mployr.com.au/v1/2fa/status \
  -H "Authorization: Bearer <token>"

# Initialize 2FA setup (returns QR code)
curl -X POST https://api.mployr.com.au/v1/2fa/setup \
  -H "Authorization: Bearer <token>"

# Enable 2FA with verification code
curl -X POST https://api.mployr.com.au/v1/2fa/enable \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"code": "123456"}'

Logging In with 2FA

When 2FA is enabled, the login process requires an additional verification step:

2fa-login.sh

# Step 1: Initial login
curl -X POST https://api.mployr.com.au/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'

# Response indicates 2FA required
{
  "success": true,
  "data": {
    "requires_2fa": true,
    "session_token": "temp-session-token..."
  }
}

# Step 2: Verify 2FA code
curl -X POST https://api.mployr.com.au/v1/2fa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "session_token": "temp-session-token...",
    "code": "123456"
  }'

Recovery Codes

Users receive recovery codes when enabling 2FA. These can be used to regain access if the authenticator app is unavailable:

Each recovery code can only be used once
Users can regenerate recovery codes at any time
Store recovery codes securely

Token Contents

The JWT token contains the following claims:

Claim	Description
sub	User ID
iat	Issued at timestamp
exp	Expiration timestamp
business_id	Associated business ID (if applicable)
scopes	User permissions/scopes

Authentication Errors

Common authentication error responses:

401 Unauthorized

Invalid or expired token. Re-authenticate to obtain a new token.

{
  "success": false,
  "message": "Unauthenticated."
}

403 Forbidden

Valid token but insufficient permissions for the requested resource.

{
  "success": false,
  "message": "This action is unauthorized."
}

Best Practices

Store tokens securely

Never expose tokens in client-side code, URLs, or logs. Use secure storage mechanisms like environment variables or encrypted storage.

Handle token expiration

Implement token refresh logic or re-authentication flow to handle expired tokens gracefully.

Enable 2FA for production

For accounts accessing sensitive data, enable two-factor authentication for additional security.

Next Steps

Now that you understand authentication, learn about rate limits and error handling.