Complete the OAuth Flow with Discord and Roblox

CA Colombia uses OAuth 2.0 to verify your identity through two external providers: Discord and Roblox. Connecting both accounts ties your Discord identity to your Roblox player, which is required before you can create characters or access any protected resources. This guide walks you through the full flow — from kicking off the authorization request to having an active session ready to use.

Overview

There are two providers: discord and roblox. You must complete the Discord OAuth flow first — it creates your CA Colombia account and issues your session cookies. Once a Discord session exists, you can link your Roblox account by running the same flow with provider=roblox. Both flows use the same two endpoints:

Step	Method	Endpoint
Initiate	`POST`	`/v1/oauth/:provider`
Callback	`GET`	`/v1/oauth/:provider`

Step-by-Step

Initiate the OAuth flow

Send a POST request to /v1/oauth/:provider with your redirectUrl. The server generates a unique state token, caches it, and returns a targetUrl — the provider’s authorization page — alongside the state value.

const res = await fetch('https://api.cacolombia.com/v1/oauth/discord', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ redirectUrl: 'https://yourapp.com/auth/callback' })
});
const { targetUrl, state } = await res.json();
window.location.href = targetUrl;

Request body

Field	Type	Required	Description
`redirectUrl`	string	✓	The URL the provider redirects back to after authorization

Response body

Field	Type	Description
`targetUrl`	string	The full authorization URL to send the user to
`state`	string	A unique token that identifies this authorization attempt

redirectUrl must belong to a domain that is registered with CA Colombia. Passing an unregistered domain returns 403 Forbidden with "Unwhitelisted redirectUrl". Contact the CA Colombia team to register your domain.

Redirect the user to the provider

Send the user to the targetUrl you received in the previous step. This is the Discord (or Roblox) authorization page where the user grants permission. You do not need to do anything else at this point — the provider handles the interaction entirely.

Handle the callback

After the user authorizes (or denies) access, the provider redirects them back to your redirectUrl with two query parameters appended: state and code. The CA Colombia server then processes these at GET /v1/oauth/:provider.

GET /v1/oauth/discord?state=<state>&code=<code>

The server validates the state against the cached value from Step 1, exchanges the code for provider tokens, and looks up or creates the user’s CA Colombia account. If the user already has valid session cookies, those tokens are refreshed rather than replaced.If anything goes wrong (invalid state, expired session, failed token exchange), the server redirects to the CA Colombia root domain rather than returning an error response. Your application should detect an absent or failed state parameter on the redirect destination and prompt the user to retry.

Session is active

On success, the server sets two HttpOnly session cookies and redirects the browser to your redirectUrl:

Cookie	Lifetime	Purpose
Access token	24 hours	Authenticates individual API requests
Refresh token	8 days	Obtains a new access token when the current one expires

Your redirectUrl also receives the state value as a query parameter so you can confirm which authorization attempt completed. From this point on, all requests that include these cookies are authenticated.

Linking a Roblox Account

Once your Discord session is established, run the same flow with provider=roblox. The server detects your existing session and attaches the Roblox identity to your account rather than creating a new one.

const res = await fetch('https://api.cacolombia.com/v1/oauth/roblox', {
  method: 'POST',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ redirectUrl: 'https://yourapp.com/auth/callback' })
});
const { targetUrl } = await res.json();
window.location.href = targetUrl;

Attempting the Roblox flow without an active Discord session returns an error. Always complete the Discord flow first.

Error Reference

Status	Error	Cause
`400`	`Invalid request params`	`:provider` is not `discord` or `roblox`
`400`	`Invalid form of body`	Request body is missing or malformed
`403`	`Unwhitelisted redirectUrl`	`redirectUrl` is not a registered domain

Session cookies grant full access to the authenticated account. Never expose them to third-party scripts, log them, or transmit them over unencrypted connections. Always use credentials: 'include' (not 'omit') when making API requests from a browser so the cookies are sent automatically.

Get Started

Core Concepts

Guides

Reference

Complete the OAuth Flow with Discord and Roblox

Overview

Step-by-Step

Linking a Roblox Account

Error Reference

​Overview

​Step-by-Step

​Linking a Roblox Account

​Error Reference

Overview

Step-by-Step

Linking a Roblox Account

Error Reference