Quick Start: Sign in with Cativa in 5 minutes

In 5 minutes you’ll have a Sign in with Cativa button working in your app. This flow is ideal when you want the end user to authenticate with their community account, without creating a new password in your product. If you only need server-to-server access (jobs, syncs, no user in the loop), use First API call, which is simpler.

What OAuth 2.0 with PKCE is

OAuth 2.0 is the standard protocol for an app to request access on behalf of a user without ever seeing their password. The user logs into Cativa, Cativa hands your app a temporary code, and your app exchanges that code for an access_token. PKCE (Proof Key for Code Exchange) is a security layer on top of OAuth. Before sending the user to log in, you generate a random secret (the code_verifier) and send only its hash (the code_challenge). When you exchange the code for a token, you reveal the original code_verifier. Cativa recomputes the hash and checks it. This stops anyone who intercepts the code from using it, because they don’t have the code_verifier.

Cativa SSO endpoints follow the OIDC standard and are organized by tenant slug ({customerName}). That slug is the community’s public subdomain. Confirm with the tenant admin which value to use. The endpoint base is https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}.

The flow at a glance

Your app generates code_verifier + code_challenge (PKCE)
Redirects the user to /authorize
User logs into Cativa and consents
Cativa redirects back with ?code=...
Your backend exchanges the code for an access_token at /token
Your app calls /userinfo and gets the profile

Create an OAuth App in the Console

Go to app.cativa.digital/admin/developers, OAuth Apps tab, click Create app.Save the returned client_id and client_secret. The secret is shown only once, store it carefully in a credentials vault.

Configure the redirect URI

In the same modal, add your redirect URI (e.g. https://myapp.com/callback, or http://localhost:3000/callback for development). The redirect_uri you send later must match exactly one of the ones registered here.

Redirect the user to /authorize

On the frontend, generate a code_verifier and code_challenge (PKCE), store the verifier in the session, and redirect to the tenant’s /authorize endpoint:

const verifier = generateRandomString(64);
const challenge = await sha256(verifier);
sessionStorage.setItem('pkce_verifier', verifier);

const params = new URLSearchParams({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://myapp.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
  code_challenge: challenge,
  code_challenge_method: 'S256',
  state: crypto.randomUUID()
});

// Replace {customerName} with the tenant slug
window.location.href = `https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/authorize?${params}`;

Store the state in the session too and check it in the callback. It protects against CSRF: if the state that comes back isn’t the one you sent, drop the request.

Exchange the code for an access_token in the callback

After the user consents, Cativa redirects to your URL with ?code=...&state=.... On the backend, POST to the same tenant’s /token endpoint with the body in application/x-www-form-urlencoded:

curl -X POST https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=CODE_FROM_CALLBACK" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=https://myapp.com/callback" \
  -d "code_verifier=VERIFIER_FROM_SESSION"

const res = await fetch(`https://apis.cativalab.digital/tenant/api/v2/sso/${customerName}/token`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    code: req.query.code,
    client_id: process.env.CATIVA_CLIENT_ID,
    client_secret: process.env.CATIVA_CLIENT_SECRET,
    redirect_uri: 'https://myapp.com/callback',
    code_verifier: req.session.pkceVerifier
  })
});
const { access_token, id_token } = await res.json();

import os
import requests

res = requests.post(
    f'https://apis.cativalab.digital/tenant/api/v2/sso/{customer_name}/token',
    data={
        'grant_type': 'authorization_code',
        'code': code,
        'client_id': os.environ['CATIVA_CLIENT_ID'],
        'client_secret': os.environ['CATIVA_CLIENT_SECRET'],
        'redirect_uri': 'https://myapp.com/callback',
        'code_verifier': session['pkce_verifier']
    }
)
tokens = res.json()

The response follows the OIDC standard:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "def50200a1b2c3..."
}

The code is single-use and expires within a few minutes. Do the exchange immediately in the callback. If you get invalid_grant, the code likely expired or was already used (for example, the user reloaded the callback page).

Fetch the user's info

Use the access_token against the userinfo endpoint:

curl https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response:

{
  "sub": "01HQ7Z3X4Y5Z6A7B8C9D0E1F2G",
  "name": "Mary Smith",
  "email": "mary@example.com",
  "picture": "https://cdn.cativa.digital/avatars/..."
}

The sub is the user’s stable ID in Cativa. Use it as the key to tie the user to your app’s session.

The tenant’s OIDC discovery document lives at https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/.well-known/openid-configuration and lists every endpoint (authorize, token, userinfo, jwks) plus the supported algorithms (S256 for PKCE, ES256 for id_token signing). The public JWKS is served at https://apis.cativalab.digital/tenant/api/v2/sso/{customerName}/jwks. Libraries like jose (Node) or PyJWT (Python) read the discovery doc and validate the id_token automatically.

This quickstart shows the happy path. Before you ship to production, validate the id_token signature via JWKS and handle OAuth errors (invalid_grant, invalid_client, PKCE failure). The full walkthrough, covering SPA, backend, and mobile, is in the Implement Sign in with Cativa guide.

Next steps

Full SSO guide

SPA, backend, and mobile, id_token validation via JWKS, token refresh, and common errors.

Tenants and Customers

Understand the customerName concept in the OIDC flow and when tenant matters in integrations.

First API call

For server-to-server integrations, use an API Key directly instead of OAuth.

Badges as Permissions

How the user’s sub connects to what they can access in the community.

Get Started

Concepts

Guides

Webhooks

Changelog

Quick Start: Sign in with Cativa in 5 minutes

What OAuth 2.0 with PKCE is

The flow at a glance

Next steps

Full SSO guide

Tenants and Customers

First API call

Badges as Permissions

​What OAuth 2.0 with PKCE is

​The flow at a glance

​Next steps

Full SSO guide

Tenants and Customers

First API call

Badges as Permissions

What OAuth 2.0 with PKCE is

The flow at a glance

Next steps