> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.cacolombia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate OAuth 2.0 Flow — POST /v1/oauth/:provider

> Start an OAuth 2.0 authorization flow with Discord or Roblox. Returns the provider authorization URL and a state token for the callback.

Use this endpoint to start an OAuth 2.0 authorization flow with either Discord or Roblox. You send a `redirectUrl` where you want the user to land after they authenticate, and the API returns the provider's authorization URL along with a `state` token. You then redirect the user to that URL — the provider handles the rest.

## Endpoint

```text theme={null}
POST /v1/oauth/:provider
```

## Path Parameters

<ParamField path="provider" type="string" required>
  The OAuth provider to authenticate with. Must be one of:

  * `discord`
  * `roblox`
</ParamField>

## Request Body

<ParamField body="redirectUrl" type="string" required>
  The URL your application wants the user redirected to after the provider callback completes. This value must be a registered URL — the API rejects any URL that has not been approved for your application.
</ParamField>

## Response

A successful `200` response returns the following fields:

<ResponseField name="targetUrl" type="string">
  The full authorization URL on the provider's side (e.g., `https://discord.com/oauth2/authorize?...`). Redirect the user to this URL to begin the consent flow.
</ResponseField>

<ResponseField name="state" type="string">
  A unique opaque token that ties this authorization request to the subsequent callback. The server stores this value server-side and validates it when the provider redirects back. You do not need to store or forward it manually — the provider appends it automatically during the callback.
</ResponseField>

## Code Example

<CodeGroup>
  ```javascript JavaScript (fetch) theme={null}
  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/callback' })
  });
  const data = await res.json();
  // { targetUrl: 'https://discord.com/oauth2/...', state: '...' }
  window.location.href = data.targetUrl;
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "targetUrl": "https://discord.com/oauth2/authorize?client_id=...&redirect_uri=...&state=1234567890abcdef&scope=identify",
  "state": "1234567890abcdef"
}
```

## Errors

| Status | Description                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The `:provider` path parameter is not `discord` or `roblox`, or the request body is missing or malformed.                          |
| `403`  | The `redirectUrl` you provided has not been registered for your application. Contact the CA Colombia team to register your domain. |

<Note>
  You must be authenticated (i.e., your request must carry a valid session cookie) before calling this endpoint. Ensure your client passes `credentials: 'include'` so any existing session cookies are forwarded with the request.
</Note>