Skip to main content
After a user grants consent on the provider’s authorization page, the provider automatically redirects them to this endpoint with a short-lived code and the original state token appended as query parameters. You do not call this endpoint directly — you configure it as the redirect URI when registering your OAuth application with Discord or Roblox, and the provider calls it on your behalf.

​
Endpoint

​
Path Parameters

​
string
required
The OAuth provider completing the flow. Must be one of:
  • discord
  • roblox

​
Query Parameters

​
string
required
The opaque state token originally issued by POST /v1/oauth/:provider. The server validates this value against its cache to confirm the callback belongs to a legitimate, unexpired authorization request.
​
string
required
The short-lived authorization code issued by the provider after the user consents. The server exchanges this code for the user’s access and refresh tokens on your behalf — you never handle the provider tokens directly.

​
Behavior

When the server receives a valid callback it:
  1. Looks up the state value in its server-side cache to retrieve the original redirectUrl and associated user context.
  2. Exchanges the code with the provider (Discord or Roblox) for that provider’s access and refresh tokens.
  3. Fetches the user’s profile from the provider and resolves or creates the corresponding CA Colombia user record.
  4. Issues a fresh pair of CA Colombia session tokens (or refreshes any existing tokens found in your cookies).
  5. Sets two HttpOnly cookies on the response:
    • Access token — valid for 24 hours.
    • Refresh token — valid for 8 days.
  6. Redirects your browser to the original redirectUrl with the state query parameter appended so your application can verify the round-trip.

​
Cookies Set

The cookies are HttpOnly and scoped to the CA Colombia domain. Your client-side JavaScript cannot read them directly; they are forwarded automatically by the browser on each request when you use credentials: 'include'.

​
After a Successful Callback

Your browser is redirected to:
You can read the state parameter on your callback page to confirm the flow completed successfully and then update your application UI accordingly.

​
Error Handling

This endpoint does not return JSON error responses. If anything goes wrong — an invalid or expired state, a bad authorization code, an unresolvable user, or a missing IP address — the server redirects the browser to the site root (/) instead. Check the final redirect destination to detect failures; a redirect to the root indicates the OAuth flow did not complete successfully.
Common reasons a callback might fail:
  • The state token has expired or was never issued (the original POST /v1/oauth/:provider was never called).
  • The code provided by the provider has already been used or has expired.
  • You are attempting to link a Roblox account but no CA Colombia user account exists for the session yet (Roblox linking requires an existing account).
  • The request originated from an IP address that could not be resolved.
If your users are landing on the root instead of your redirectUrl, initiate a fresh OAuth flow by calling POST /v1/oauth/:provider again.
For Roblox OAuth specifically, the user must already have a CA Colombia account (created via a prior Discord login) before linking their Roblox identity. Attempting a Roblox flow without an existing account will result in a redirect to the root.