2. Session Token Status Check

Session Token Status Check

Before making API calls that require authentication, it's important to verify whether your existing session token is still valid. This scenario demonstrates how to check the status of a session token.

Key benefits:

Verify token validity
Determine if a new authentication is required
Retrieve user information and permissions in a single request
Check if additional authentication steps (like MFA) are needed

Use Cases

Application startup to determine if the user is already logged in
After page refresh to verify session persistence
Checking if MFA authentication is complete for protected operations

This endpoint is particularly useful for client applications that need to maintain session state across page refreshes or application restarts.

Step 1 - Check session token status

This endpoint verifies the current authentication status and returns detailed session information.

Validates if the provided token is still active and usable
Returns login status and token unlock state
Provides user profile information if the token is valid
Includes permission rights and system settings

You can use this endpoint to determine if you need to re-authenticate or if your current token can be used for API calls.

Endpoint

CODE

GET /login

Request

JSON

GET /login?token=v8Cc0Ld84bYBI1dGs3blA8nBJBWEAdqzGA0vKytkfsGxJv1nIglKVhbgSQzCdx8W&returnToken=true

Response

JSON

{
  "logged": true,
  "isUnlocked": true,
  "token": "v8Cc0Ld84bYBI1dGs3blA8nBJBWEAdqzGA0vKytkfsGxJv1nIglKVhbgSQzCdx8W",
  "tenant": "default",
  "user": {
    ...
  },
  "settings": {
    ...
  },
  "rights": [
    ...
  ],
  ...
}

The response provides comprehensive information about the session token status.

logged: Indicates if the token is valid and the user is authenticated
isUnlocked: Shows if the token is fully unlocked (especially important for MFA-enabled accounts)
rights: Lists all permissions the user has in the system
user: Contains detailed user profile information

Based on this response, your application can make decisions about whether to proceed with API calls or it needs to obtain a new session token.

Session Token Status Check Summary

If logged: true and isUnlocked: true, the token is valid and can be used for API calls
If logged: true but isUnlocked: false, the token requires additional authentication (MFA)
If logged: false, the token is invalid or expired, and a new login is required

Example Usage in Client Applications

See our OpenAPI documentation to learn about the full set of API endpoints and parameters.

Please use proper exception handling and function decomposition in your own code. The code is provided for illustrative purposes only and is not intended for production use.

JAVASCRIPT

// Check session token status
const URL = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";

const TOKEN = "YOUR_TOKEN";

try {
    const response = await fetch(`${URL}${API_PATH}/login?token=${TOKEN}&returnToken=true`);
    if (!response.ok) {
        throw new Error(`Login check failed: ${response.status} ${response.statusText}`);
    }

    const statusData = await response.json();

    // Check if the token is valid and unlocked
    if (statusData.logged && statusData.isUnlocked) {
        console.log('Token is valid and unlocked');

    } else if (statusData.logged && !statusData.isUnlocked) {
        console.log('Token is valid but requires MFA unlock');

    } else {
        console.log('Token is invalid or expired');
    }

} catch (error) {
    console.error('Error in login check flow:', error.message);
}