Sign In With CATAPA

This guide explains how to add "Sign in with CATAPA" to your application using the OAuth2 Authorization Code flow with user consent.

Prerequisites

Before you begin, you need to create an OAuth Client. See https://gdplabs.gitbook.io/catapa-api/get-started/authentication-and-authorization#create-an-oauth-client. Make sure the Authorized Grant Type contains authorization_code.

Get the following from the OAuth Client:

Item	Description
client_id	Your application's unique identifier
client_secret	Your application's secret key (keep this confidential)
redirect_uri	The callback URL in your app where CATAPA will redirect after authorization

Flow Diagram

Step-by-Step Integration

1

Create the "Sign in with CATAPA" Link

In your application's frontend, create a link or button that redirects the user to CATAPA's authorization page:

https://accounts-apps.catapa.com/oauth2/authorize
    ?response_type=code
    &client_id={YOUR_CLIENT_ID}
    &redirect_uri={YOUR_REDIRECT_URI}
    &scope=
    &state={STATE}

Parameters:

Parameter	Required	Description
response_type	Yes	Must be code
client_id	Yes	Your application's client ID
redirect_uri	Yes	Your callback URL. Must exactly match a registered redirect URI
scope	Yes	Space-separated list of scopes. Currently, set it to empty (no value)
state	Recommended	A random string to prevent CSRF attacks. You must verify this value in the callback

Example HTML:

<a href="https://accounts-apps.catapa.com/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https://yourapp.com/callback&scope=&state=RANDOM_STRING">
  Sign in with CATAPA
</a>

2

User Logs In and Grants Consent

After clicking the link, the user is taken to CATAPA where they:

1. Log in — If the user is not already logged into CATAPA, they will be prompted to log in

2. Review permissions — CATAPA shows a consent page with your application's name and the permissions being requested

3. Authorize or Deny — The user decides whether to grant access

You do not need to implement anything for this step. CATAPA handles it entirely.

3

Handle the Redirect Callback

After the user authorizes (or denies) the request, CATAPA redirects the user's browser to your redirect_uri.

Successful authorization:

https://yourapp.com/callback?code={AUTHORIZATION_CODE}&state={STATE}&tenant={TENANT}

Parameter	Description
code	The authorization code. Use this in the next step to get an access token
state	Must match the state you sent in Step 1. Reject the request if it doesn't match
tenant	The CATAPA tenant identifier of the authenticated user. Store this — you will need it for API calls

Denied authorization:

https://yourapp.com/callback?error=access_denied&error_description=...&state={STATE}

4

Exchange the Code for an Access Token

Your backend must exchange the authorization code for an access token. This call must be made server-side to keep your client_secret confidential.

Request:

HTTP

POST /oauth/token HTTP/1.1
Host: api.catapa.com
Authorization: Basic [BASE64_ENCODED_CREDENTIALS]
Content-Type: application/x-www-form-urlencoded
Tenant: {TENANT}
Content-Length: [LENGTH]

grant_type=authorization_code&code={AUTHORIZATION_CODE}&redirect_uri={YOUR_REDIRECT_URI}

cURL

Python

Important: The token endpoint is /oauth/token (not /oauth2/token).

Parameters:

Parameter	Required	Description
grant_type	Yes	Must be authorization_code
code	Yes	The authorization code from Step 3
redirect_uri	Yes	Must exactly match the redirect_uri used in Step 1

Authentication: HTTP Basic Auth with client_id as the username and client_secret as the password.

Response:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400
}

Field	Description
access_token	JWT token to use in API requests
refresh_token	Token to obtain a new access token when the current one expires
token_type	Always Bearer
expires_in	Token lifetime in seconds (e.g., 86400 = 24 hours)

5

Get User Information

Use the access token and tenant to retrieve the authenticated user's information:

HTTP

GET /v1/users/me HTTP/1.1
Host: api.catapa.com
Authorization: Bearer {ACCESS_TOKEN}
Tenant: {TENANT}

cURL

Python

The Tenant header is required for all CATAPA API calls.

6

Refresh the Access Token (Optional)

When the access token expires, use the refresh token to get a new one without requiring the user to log in again:

HTTP

POST /oauth/token HTTP/1.1
Host: api.catapa.com
Authorization: Basic {BASE64({YOUR_CLIENT_ID}:{YOUR_CLIENT_SECRET})}
Content-Type: application/x-www-form-urlencoded
Tenant: {TENANT}

grant_type=refresh_token&refresh_token={REFRESH_TOKEN}

cURL

Python

Response: Same format as Step 4, with a new access_token and refresh_token.

Quick Reference

Endpoints

Endpoint	Method	Description
/oauth2/authorize	GET	Start the authorization flow (via browser redirect)
/oauth/token	POST	Exchange code for tokens, or refresh tokens
/v1/users/me	GET	Get the authenticated user's information

Required Headers for API Calls

Header	Value	Description
Authorization	Bearer {ACCESS_TOKEN}	The access token from the token exchange
Tenant	{TENANT}	The tenant value received in the authorization callback

Error Handling

Authorization Errors (Step 3)

If something goes wrong during authorization, CATAPA redirects to your redirect_uri with error parameters:

https://yourapp.com/callback?error={ERROR_CODE}&error_description={DESCRIPTION}&state={STATE}

Error Code	Description
invalid_request	Missing or invalid required parameter
unauthorized_client	Your app is not authorized for this grant type
access_denied	The user denied the consent request
invalid_scope	Requested scope is invalid or unknown
server_error	Unexpected server error

Token Errors (Step 4)

The token endpoint returns HTTP error codes with a JSON body:

{
    "error": "invalid_grant",
    "error_description": "Authorization code has expired or is invalid"
}

Rate Limiting

The authorization and token endpoints are rate-limited. Excessive failed requests will result in HTTP 429 Too Many Requests.

Security Best Practices

1. Always validate state — Compare the returned state with the one you sent to prevent CSRF attacks

2. Exchange the code server-side — Never expose your client_secret in frontend/client-side code

3. Store tokens securely — Keep access_token and refresh_token in a secure server-side store

4. Store the tenant value — You will need it as a header for all subsequent API calls

5. Handle token expiration — Use the refresh token to seamlessly renew access without re-prompting the user

6. Use HTTPS — All communication with CATAPA must be over HTTPS in production

Complete Example (Python)

import requests
from urllib.parse import urlencode

CLIENT_ID = "your_client_id"
CLIENT_SECRET = "your_client_secret"
REDIRECT_URI = "https://yourapp.com/callback"
CATAPA_ACCOUNTS_URL = "https://accounts-apps.catapa.com"
CATAPA_API_URL = "https://api.catapa.com"


# Step 1: Generate the authorization URL
def get_authorize_url(state: str) -> str:
    params = {
        "response_type": "code",
        "client_id": CLIENT_ID,
        "redirect_uri": REDIRECT_URI,
        "scope": "all",
        "state": state,
    }
    return f"{CATAPA_ACCOUNTS_URL}/oauth2/authorize?{urlencode(params)}"


# Step 4: Exchange authorization code for tokens
def exchange_code_for_tokens(code: str, tenant: str) -> dict:
    response = requests.post(
        f"{CATAPA_API_URL}/oauth/token",
        auth=(CLIENT_ID, CLIENT_SECRET),
        headers={"Tenant": tenant},
        data={
            "grant_type": "authorization_code",
            "code": code,
            "redirect_uri": REDIRECT_URI,
        },
    )
    response.raise_for_status()
    return response.json()


# Step 5: Get user information
def get_user_info(access_token: str, tenant: str) -> dict:
    response = requests.get(
        f"{CATAPA_API_URL}/v1/users/me",
        headers={
            "Authorization": f"Bearer {access_token}",
            "Tenant": tenant,
        },
    )
    response.raise_for_status()
    return response.json()


# Step 6: Refresh the access token
def refresh_access_token(refresh_token: str, tenant: str) -> dict:
    response = requests.post(
        f"{CATAPA_API_URL}/oauth/token",
        auth=(CLIENT_ID, CLIENT_SECRET),
        headers={"Tenant": tenant},
        data={
            "grant_type": "refresh_token",
            "refresh_token": refresh_token,
        },
    )
    response.raise_for_status()
    return response.json()

FAQ

Do I need to implement the consent/login page?

No. CATAPA handles user authentication and consent entirely. Your app only needs to redirect the user and handle the callback.

Can I skip the consent step?

No. If your client is configured to require consent, the user must explicitly authorize your application. This cannot be bypassed.

How long does the authorization code last?

Authorization codes are short-lived (typically 5 minutes). Exchange it for tokens immediately after receiving it.

Can I use the access token for multiple tenants?

No. The access token is scoped to the tenant returned in the callback. You must include the correct Tenant header in every API call.