Skip to main content
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 Cativa community account.
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.
1

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.
2

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).
3

Redirect the user to /authorize

On the frontend, generate a code_verifier and code_challenge (PKCE), then 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}`;
4

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_SECRET" \
  -d "redirect_uri=https://myapp.com/callback" \
  -d "code_verifier=VERIFIER_FROM_SESSION"
The response follows the OIDC standard and contains access_token, token_type, expires_in and id_token.
5

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 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.

​
Next steps

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.