1. Authentication & Security

Authentication & Security Overview

Secure authentication is the foundation of Circularo's security model. This section provides comprehensive guidance on available authentication methods, helping you choose and implement the right approach for your integration needs.

Authentication Methods

Circularo supports three primary authentication approaches, each designed for specific use cases:

Session Tokens: Short-lived credentials for interactive user sessions
API Tokens: Long-lived credentials for server-to-server integrations
Third-Party Authentication: Authentication using external identity providers

Session Tokens

Session tokens are temporary authentication credentials designed for interactive user sessions:

Generated through username/password authentication
Valid for 30 days by default
Support for Multi-Factor Authentication (MFA)
Can be checked for validity and terminated when no longer needed
Ideal for web applications and interactive sessions

API Tokens

API tokens are long-lived credentials designed for server-to-server integrations:

Valid for 10 years by default
Created using an authenticated session token
Inherit all permissions from the creating user
Can be revoked or rotated as needed
Ideal for automated processes and backend services

Third-Party Authentication

Third-party authentication leverages external identity providers:

Supports various identity providers and authentication protocols
Requires configuration and coordination with Circularo support
Results in standard session tokens after successful authentication
Ideal for enterprise environments with existing identity systems

Authentication Flow Comparison

Session Token Flow

1. Authenticate with username and password
2. Complete MFA verification if enabled
3. Use the session token for API requests
4. Check token validity as needed
5. Terminate the session when finished

API Token Flow

1. Authenticate to obtain a session token
2. Create an API token using the session token
3. Store the API token securely
4. Use the API token for all automated operations
5. Rotate or revoke the token when necessary

Third-Party Authentication Flow

1. Redirect user to the external identity provider
2. User authenticates with the provider
3. Provider redirects back with authentication data
4. Exchange the authentication data for a session token
5. Use the session token for API operations

Security Best Practices

Store tokens securely: Never expose tokens in client-side code or public repositories
Implement proper token management: Terminate sessions when no longer needed
Enable Multi-Factor Authentication: Add an extra layer of security for sensitive accounts
Rotate tokens regularly: Especially for long-lived API tokens in production environments

All authentication tokens provide access to your Circularo account and should be handled with appropriate security measures.

Token Usage in API Requests

All Circularo token protected API endpoints accept token as a query or a cookie parameter:

HTTP

GET /api/v1/documents/:id?token=YOUR_TOKEN_HERE

Circularo does not support Bearer Token authentication in the Authorization header. Always provide token as a query or cookie parameter.

Getting Started

Explore the subsections to learn more about each authentication method.

1. User Logins (Session Tokens)

2. Integration Credentials (API Tokens)

3. Third-Party Authentication