OAuth Flow

The authentication flow differs based on whether you’re using a private or public application.

​

Private Application Flow (Authorization Code)

1. Redirect Users to Authorization URL

   Construct the authorization URL with your client_id and callback_url:

   const authUrl = new URL("https://clerk.coloop.ai/oauth/authorize");
   authUrl.searchParams.append("client_id", "your_client_id");
   authUrl.searchParams.append("redirect_uri", "your_callback_url");
   authUrl.searchParams.append("response_type", "code");
   authUrl.searchParams.append("scope", "email profile");
   // Redirect user to authUrl

2. Handle the Callback

   After authorization, CoLoop redirects to your callback URL with an authorization code:

   // Example callback URL:
   // https://your-domain.com/oauth2/callback?code=abc123...

3. Exchange Code for Tokens

   Make a POST request to the token endpoint:

   const response = await fetch("https://clerk.coloop.ai/oauth/token", {
     method: "POST",
     headers: {
       "Content-Type": "application/x-www-form-urlencoded",
     },
     body: new URLSearchParams({
       grant_type: "authorization_code",
       client_id: "your_client_id",
       client_secret: "your_client_secret",
       code: "authorization_code_from_callback",
       redirect_uri: "your_callback_url"
     })
   });
   const tokens = await response.json();
   // {
   //   "access_token": "...",
   //   "refresh_token": "...",
   //   "scope": "email profile",
   //   "token_type": "bearer",
   //   "expires_in": 7200
   // }

​

Public Application Flow (PKCE)

1. Generate PKCE Challenge

   // Generate a random code verifier
   function generateCodeVerifier() {
     const array = new Uint8Array(32);
     crypto.getRandomValues(array);
     return base64UrlEncode(array);
   }
   // Create code challenge
   async function generateCodeChallenge(verifier) {
     const encoder = new TextEncoder();
     const data = encoder.encode(verifier);
     const digest = await crypto.subtle.digest("SHA-256", data);
     return base64UrlEncode(new Uint8Array(digest));
   }
   const codeVerifier = generateCodeVerifier();
   const codeChallenge = await generateCodeChallenge(codeVerifier);

2. Redirect to Authorization URL with PKCE

   const authUrl = new URL("https://clerk.coloop.ai/oauth/authorize");
   authUrl.searchParams.append("client_id", "your_client_id");
   authUrl.searchParams.append("redirect_uri", "your_callback_url");
   authUrl.searchParams.append("response_type", "code");
   authUrl.searchParams.append("scope", "email profile");
   authUrl.searchParams.append("code_challenge", codeChallenge);
   authUrl.searchParams.append("code_challenge_method", "S256");
   // Redirect user to authUrl

3. Exchange Code for Tokens

   const response = await fetch("https://clerk.coloop.ai/oauth/token", {
     method: "POST",
     headers: {
       "Content-Type": "application/x-www-form-urlencoded",
     },
     body: new URLSearchParams({
       grant_type: "authorization_code",
       client_id: "your_client_id",
       code: "authorization_code_from_callback",
       code_verifier: codeVerifier,
       redirect_uri: "your_callback_url"
     })
   });
   const tokens = await response.json();

​

Using the Access Token

For both flows, use the access token to make authenticated requests:

const userInfo = await fetch("https://clerk.coloop.ai/oauth/userinfo", {
  headers: {
    "Authorization": `Bearer ${access_token}`
  }
});
const user = await userInfo.json();
// {
//   "email": "user@example.com",
//   "email_verified": true,
//   "name": "John Doe",
//   ...
// }

​

Token Refresh

When the access token expires (after 2 hours), use the refresh token to get a new one:

const response = await fetch("https://clerk.coloop.ai/oauth/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
    grant_type: "refresh_token",
    client_id: "your_client_id",
    refresh_token: "your_refresh_token",
    // Include client_secret only for private applications
    ...(isPrivateApp && { client_secret: "your_client_secret" })
  })
});
const tokens = await response.json();

​

Security Considerations

1. Token Storage
   • Store access tokens and refresh tokens securely
   • For public applications, use secure browser storage mechanisms
   • For private applications, use server-side secure storage
2. PKCE Verifier
   • Generate a new code verifier for each authorization request
   • Store the verifier securely until the token exchange
3. Error Handling
   • Handle token expiration and refresh scenarios gracefully
   • Implement retry logic with exponential backoff for failed requests