1. OAuth Authentication Integration

OAuth Authentication Integration

This guide demonstrates how to implement OAuth-based authentication with Circularo for third-party applications. OAuth integration allows users to authenticate using their existing identity provider accounts (such as Google, Microsoft, or other configured providers).

This is an advanced authentication scenario primarily intended for custom integrations that require OAuth-based login flows. Most integrations should use the standard session token or API token authentication methods described in previous sections.

Prerequisites

Before implementing OAuth authentication, please note:

Your callback URL must be whitelisted by Circularo support team
This integration uses endpoints that may only be presented in full Circularo OpenAPI schema
This flow is intended for specialized integration scenarios

Contact Circularo support to have your callback URL whitelisted before attempting to implement this authentication flow.

Step 1 - Initiate OAuth authentication flow

This endpoint initiates the OAuth authentication flow with the specified identity provider. When called, it redirects the user to the provider's authentication page (e.g., Google login page).

The strategy_name parameter specifies which OAuth provider to use (e.g., "google", "microsoft")
The callback parameter defines where the user will be redirected after successful authentication
The domain parameter specifies the Circularo instance domain

The callback URL must be pre-approved and whitelisted by Circularo support team. Unauthorized callback URLs will be rejected for security reasons.

Endpoint

CODE

GET /oauth/:strategy_name

Request

JSON

GET /oauth/google?callback=https%3A%2F%2Fcustom.domain.com%2Flogin&domain=https%3A%2F%2Fsandbox.circularo.com%2F

Authentication Flow

1. The user is redirected to the identity provider's authentication page
2. User authenticates with their credentials on the provider's page
3. Upon successful authentication, the provider redirects back to Circularo (domain) URL to finalize the authentication process
4. Circularo redirects to your callback URL with a temporary code parameter that must be exchanged for a session token

This endpoint may not be visible in the integrators' OpenAPI schema, but it is available in the full OpenAPI specification.

After successful authentication, the application redirects back to your callback URL with a query parameter code like this:

CODE

https://custom.domain.com/login?code=12448c3c-040d-4fa6-a0cf-2dec840aab3c

This code is temporary and must be exchanged for a session token in the next step.

Step 2 - Exchange temporary code for session token

This endpoint exchanges the temporary code received in the callback for a standard Circularo session token that can be used for API authentication.

The code is single-use and expires shortly if not used
The resulting token is a standard Circularo session token with the same properties as tokens obtained through direct login
The token inherits all permissions from the authenticated user

This step completes the OAuth authentication flow, providing you with a standard session token that can be used for all subsequent API calls.

Endpoint

CODE

GET /oauth/code

Request

JSON

GET /oauth/code?code=12448c3c-040d-4fa6-a0cf-2dec840aab3c

Response

JSON

{
  "token": "VwT3j36JSZ5oiyiYCVN4thIbdv3XgL9LvWldeM4BzQIeQHIH2cSXS8jwqeOpcK30"
}

The response contains a standard Circularo session token that can be used for all API operations.

This token functions exactly like tokens obtained through standard username/password authentication
It should be included as a query parameter in subsequent API requests
The token is subject to the same validity period and security rules as standard session tokens

Store this token securely and follow the same security practices as with standard session tokens.

OAuth Integration Summary

OAuth authentication provides a way for users to authenticate with Circularo using their existing identity provider accounts. This approach offers several benefits:

Simplified user experience through single sign-on
Reduced password management burden
Leveraging existing identity provider security features
Consistent authentication experience across applications

Implementation Considerations

When implementing OAuth authentication with Circularo:

Ensure your callback URL is whitelisted by contacting Circularo support
Implement proper error handling for authentication failures
Consider the user experience flow, especially for mobile applications
Be aware that this integration uses endpoints that may only be specified in the full OpenAPI schema

Example Implementation

See our full 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

// OAuth authentication flow example
const CIRCULARO_DOMAIN = "https://sandbox.circularo.com";
const API_PATH = "/api/v1";
const OAUTH_PROVIDER = "google";
const CALLBACK_URL = "https://your-app.com/auth/callback";

// Step 1: Redirect user to OAuth provider
const authUrl = `${CIRCULARO_DOMAIN}${API_PATH}/oauth/${OAUTH_PROVIDER}?callback=${encodeURIComponent(CALLBACK_URL)}&domain=${encodeURIComponent(CIRCULARO_DOMAIN)}`;
window.location.href = authUrl;

// Step 2: Handle callback and exchange code for token
// This would be called when the provider redirects back to your callback URL
const code = getCodeFromCallback();
try {
    const response = await fetch(`${CIRCULARO_DOMAIN}${API_PATH}/oauth/code?code=${code}`);
    if (!response.ok) {
        throw new Error(`Failed to exchange code: ${response.status} ${response.statusText}`);
    }

    const { token } = await response.json();

} catch (error) {
    console.error('OAuth authentication error', error.message);
}