Session-based Authentication Overview
Session-based authentication is the primary method for authenticating users in the Circularo system. It provides a secure way to access the API.
What are Session Tokens?
Session tokens are temporary authentication credentials that:
-
Provide secure access to the Circularo API after successful authentication
-
Are valid for 30 days by default
-
Can be used across multiple API requests
-
Eliminate the need to send credentials with each request
Authentication Methods
Circularo supports multiple authentication methods to accommodate different security requirements:
-
Standard Authentication: Simple username and password login
-
Multi-Factor Authentication (MFA): Additional verification step after password entry
-
Recovery Code Authentication: Emergency access when standard MFA methods are unavailable
Token Lifecycle
-
Creation: Generated upon successful authentication
-
Validation: Can be checked for validity
-
Usage: Included as a query parameter in API requests
-
Termination: Invalidated through explicit logout or expiration
Security Considerations
-
Store session tokens securely and never expose them in client-side code
-
Implement proper token management including logout when sessions are no longer needed
-
For server-to-server integrations, consider using API tokens instead
-
Enable Multi-Factor Authentication for sensitive accounts
Session tokens provide full access to a user's account. Always handle them with appropriate security measures.
Common Use Cases
-
Interactive web applications: User sessions in browser-based interfaces
-
Mobile applications: Authentication for native mobile clients
-
Short-lived integrations: Temporary access for one-time operations
For long-lived server-to-server integrations, API tokens (covered in the next section) are recommended over session tokens.
Authentication Flow
A typical authentication flow involves:
-
1. Authenticating with username and password
-
2. Completing any required MFA challenges (if enabled)
-
3. Using the resulting session token for API operations
-
4. Checking token validity when needed
-
5. Logging out to terminate the session when finished
The scenarios in this section demonstrate each step of this process in detail.