Step 1: Login

Send a POST request to /api/v1/auth/login with the staff member's email and password.

Request Body

{
  "email": "[email protected]",
  "password": "your-password"
}

Response

A successful login returns an access token, a refresh token, expiry information, and the authenticated user's profile.

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "v1.MbQvMjY0NDk1N...",
  "expires_in": 3600,
  "token_type": "bearer",
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "[email protected]",
    "user_type": "system_user",
    "merchant_id": "m_abc123",
    "location": {
      "id": "loc_456",
      "name": "Downtown Branch"
    },
    "locations": [
      {
        "id": "loc_456",
        "name": "Downtown Branch"
      }
    ]
  }
}

User Types

• system_user — A staff member bound to a specific location. API calls are scoped to that location.
• owner — The merchant owner with access to all locations under the merchant account.

Step 2: Use the Token

Include the access token in the Authorization header of every API request.

Authorization: Bearer <access_token>

Example

curl -X GET https://api.forloy.com/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Step 3: Check Identity

Call GET /api/v1/auth/me to verify that your token is valid and retrieve the current user's profile. This is useful for confirming identity and getting context like the active location.

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "[email protected]",
  "user_type": "system_user",
  "merchant_id": "m_abc123",
  "location": {
    "id": "loc_456",
    "name": "Downtown Branch"
  },
  "locations": [
    {
      "id": "loc_456",
      "name": "Downtown Branch"
    }
  ]
}

Step 4: Refresh Tokens

When the access token expires (check the expires_in value from the login response), use the refresh token to obtain a new token pair.

Request Body

{
  "refresh_token": "your-refresh-token"
}

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "v1.NwQvMjY0NDk2O...",
  "expires_in": 3600
}

Important: Store the new refresh token immediately. The old refresh token is invalidated after each refresh call.

Best Practices

• Store tokens securely. Never log tokens, embed them in URLs, or expose them in client-side code.
• Refresh proactively before expiry. Schedule a refresh slightly before the expires_in window closes to avoid failed requests.
• Handle 401 errors gracefully. If a request returns a 401 Unauthorized response, refresh the token and retry the original request.
• Use the location from the user object. The location_id returned in the user profile should be used for subsequent API calls that require a location context.

Next Step

Now that you can authenticate, learn how to record customer activity.

Continue to Transactions →