Skip to main content
Authenticated API

These endpoints require a valid JWT Bearer token. All session endpoints use POST and accept the access token in the request body. Accessible via the API gateway at /v1/auth/sessions/*.

Session Management

Manage user sessions, token refresh, and session lifecycle.

Overview​

Olympus Cloud uses JWT-based sessions with refresh tokens:

TokenLifetimeStoragePurpose
Access Token1 hourMemoryAPI authentication
Refresh Token30 daysSecure storageObtain new access tokens
Session30 daysServer-sideTrack active sessions

Token Refresh​

Obtain a new access token using a refresh token.

Request​

POST /api/v1/auth/refresh
Content-Type: application/json
{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

Response​

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "bmV3IHJlZnJlc2ggdG9rZW4...",
  "token_type": "Bearer",
  "expires_in": 3600
}
note

A new refresh token is issued with each refresh (rotation).

Logout​

End the current session.

Request​

POST /api/v1/auth/logout
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "refresh_token": "current_refresh_token"
}

Response​

{
  "logged_out": true,
  "session_ended": "2026-01-18T10:30:00Z"
}

List Active Sessions​

View all active sessions for the current user.

Request​

POST /api/v1/auth/sessions/list
Content-Type: application/json
{
  "access_token": "current_access_token"
}

Response​

{
  "sessions": [
    {
      "id": "session-abc123",
      "device": "Chrome on MacOS",
      "ip_address": "192.168.1.100",
      "location": "San Francisco, CA",
      "created_at": "2026-01-15T08:00:00Z",
      "last_active": "2026-01-18T10:30:00Z",
      "is_current": true
    },
    {
      "id": "session-def456",
      "device": "Olympus Mobile App on iPhone",
      "ip_address": "10.0.0.50",
      "location": "San Francisco, CA",
      "created_at": "2026-01-10T12:00:00Z",
      "last_active": "2026-01-17T18:00:00Z",
      "is_current": false
    }
  ]
}

Revoke Session​

End a specific session (sign out from a device).

Request​

POST /api/v1/auth/sessions/revoke
Content-Type: application/json
{
  "access_token": "current_access_token",
  "session_id": "session-def456"
}

Response​

{
  "revoked": true
}

Revoke All Other Sessions​

Sign out from all devices except the current one.

Request​

POST /api/v1/auth/sessions/revoke/all
Content-Type: application/json
{
  "access_token": "current_access_token"
}

Response​

{
  "revoked": 3
}

Token Validation​

Verify if a token is still valid and get the associated user context.

Request​

POST /api/v1/auth/validate
Content-Type: application/json
{
  "token": "access_token_to_validate"
}

POS Token Validation​

A specialized validation endpoint for POS terminals:

POST /api/v1/auth/validate/pos
Content-Type: application/json

JWT Token Structure​

Access Token Claims​

ClaimDescription
subUser ID
tidTenant ID
lidLocation ID (if applicable)
rolesUser roles array
permsPermissions array
expExpiration timestamp
iatIssued at timestamp
jtiUnique token ID

Example Decoded Token​

{
  "sub": "user-123",
  "tid": "tenant-abc123",
  "lid": "loc-xyz789",
  "roles": ["manager"],
  "perms": ["orders.*", "payments.process"],
  "exp": 1737199800,
  "iat": 1737196200,
  "jti": "token-unique-id"
}

Session Limits​

SettingDefaultDescription
Max sessions per user10Oldest session revoked when exceeded
Session timeout30 daysInactive session expiration
Refresh token rotationEnabledNew token issued on each refresh
Concurrent sessionsAllowedMultiple devices supported

Error Responses​

Token Expired (401)​

{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Access token has expired",
    "expired_at": "2026-01-18T10:00:00Z"
  }
}

Invalid Refresh Token (401)​

{
  "error": {
    "code": "INVALID_REFRESH_TOKEN",
    "message": "Refresh token is invalid or has been revoked"
  }
}

Session Not Found (404)​

{
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "Session does not exist or has been revoked"
  }
}

Best Practices​

  1. Refresh proactively - Refresh tokens 5 minutes before expiration
  2. Handle token errors - Redirect to login on refresh failure
  3. Secure storage - Use secure storage for refresh tokens
  4. Monitor sessions - Allow users to view and manage sessions
  5. Implement logout - Properly revoke tokens on user logout

Code Examples​

Token Refresh (TypeScript)​

const API_BASE = 'https://dev.api.olympuscloud.ai/v1';

// Refresh tokens before they expire (recommended: 5 minutes before expiry)
async function refreshAccessToken(refreshToken: string) {
  const response = await fetch(`${API_BASE}/auth/refresh`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ refresh_token: refreshToken }),
  });
  const data = await response.json();
  // data.status.access_token contains the new JWT
  return data.status;
}

const newTokens = await refreshAccessToken(refreshToken);
console.log('Token refreshed, new access_token:', newTokens.access_token);

Session Management​

const API_BASE = 'https://dev.api.olympuscloud.ai/v1';
const headers = {
  'Content-Type': 'application/json',
};

// List active sessions
const sessions = await fetch(`${API_BASE}/auth/sessions/list`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ access_token: accessToken }),
}).then(res => res.json());

// Revoke a specific session
await fetch(`${API_BASE}/auth/sessions/revoke`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    access_token: accessToken,
    session_id: 'session-def456',
  }),
});

// Revoke all other sessions
await fetch(`${API_BASE}/auth/sessions/revoke/all`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ access_token: accessToken }),
});