OAuth Integration

Implement OAuth 2.0 authentication for user-facing applications.

This guide explains how to implement OAuth 2.0 authentication for applications that need to act on behalf of users.

Overview

OAuth 2.0 is the industry-standard protocol for authorization. Use it when your application needs to:

Access user data on their behalf
Integrate with third-party services
Build multi-tenant applications

Prerequisites

Before implementing OAuth, you’ll need:

A Celeris account with OAuth enabled
An OAuth application created in your dashboard
Your client_id and client_secret

Creating an OAuth Application

Register your application

Go to Settings > OAuth Applications and click Create Application.

Configure redirect URIs

Add the URLs where users will be redirected after authorization:

https://yourapp.com/auth/callback
http://localhost:3000/auth/callback

Note your credentials

Copy your client_id and client_secret. The secret is only shown once.

Authorization Flow

Step 1: Redirect to Authorization URL

Redirect users to the Celeris authorization endpoint:

const authUrl = new URL('https://auth.celeriscloud.io/authorize');
authUrl.searchParams.set('client_id', CLIENT_ID);
authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', 'agents:read agents:write');
authUrl.searchParams.set('state', generateRandomState());

// Redirect user
window.location.href = authUrl.toString();

Step 2: Handle the Callback

After authorization, the user is redirected to your callback URL with a code:

// GET /auth/callback?code=xxx&state=yyy

app.get('/auth/callback', async (req, res) => {
  const { code, state } = req.query;

  // Verify state to prevent CSRF
  if (state !== session.state) {
    return res.status(400).send('Invalid state');
  }

  // Exchange code for tokens
  const tokens = await exchangeCodeForTokens(code);

  // Store tokens securely
  session.accessToken = tokens.access_token;
  session.refreshToken = tokens.refresh_token;

  res.redirect('/dashboard');
});

Step 3: Exchange Code for Tokens

Exchange the authorization code for access and refresh tokens:

async function exchangeCodeForTokens(code) {
  const response = await fetch('https://auth.celeriscloud.io/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      code: code,
      redirect_uri: REDIRECT_URI,
    }),
  });

  return response.json();
}

Token Response

A successful token exchange returns:

{
  "access_token": "cel_at_xxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "cel_rt_xxxx",
  "scope": "agents:read agents:write"
}

Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to get new tokens:

async function refreshAccessToken(refreshToken) {
  const response = await fetch('https://auth.celeriscloud.io/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
      grant_type: 'refresh_token',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      refresh_token: refreshToken,
    }),
  });

  return response.json();
}

Warning

Store refresh tokens securely. They can be used to obtain new access tokens indefinitely.

Scopes

Request only the scopes your application needs:

Scope	Description
`profile`	Read user profile information
`agents:read`	Read agent configurations
`agents:write`	Create and modify agents
`workflows:read`	Read workflows
`workflows:write`	Create and modify workflows
`executions:read`	View execution history