1. User Logins (Session Tokens)
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.