Get Started with CA Colombia API

This guide walks you through the four essential steps to get up and running with CA Colombia API. By the end, you’ll have an authenticated session, a retrieved user profile, a newly created character, and an active WebSocket connection listening for live platform events.

Authenticate via OAuth

Before you can call any protected endpoint, you need an authenticated session. Start the OAuth flow by posting to POST /v1/oauth/:provider with your chosen provider (discord or roblox) and a redirectUrl that the API will send the player back to after they authorize.

You must complete Discord OAuth before you can link a Roblox account. Attempting the Roblox flow without an existing Discord-linked session will fail.

Request

curl -X POST https://api.cacolombia.com/v1/oauth/discord \
  -H "Content-Type: application/json" \
  -d '{"redirectUrl": "https://yourapp.com/auth/callback"}'

Response

{
  "targetUrl": "https://discord.com/oauth2/authorize?client_id=...&state=01J...",
  "state": "01J9XK2M4N7P3Q8R5T6W"
}

Redirect your user to targetUrl. After they authorize, the API will redirect them back to your redirectUrl with the state parameter appended as a query string. Session cookies (access_token and refresh_token) are set automatically on the callback — you do not need to handle tokens yourself.

Retrieve Your User Profile

Once authenticated, retrieve the current user’s profile with GET /v1/users/{userId}. You must pass the user’s own ID — you cannot view another user’s profile unless you have elevated permissions.Append ?providers=true to include linked OAuth provider details, or ?signature=true to include character signature data.Request

curl https://api.cacolombia.com/v1/users/01J9XK2M4N7P3Q8R5T6W \
  --cookie "access_token=<your_session_cookie>"

Response

{
  "userId": "01J9XK2M4N7P3Q8R5T6W",
  "permissions": "1",
  "activeCharacter": null,
  "maxCharacters": 3,
  "characters": [],
  "createdAt": "2024-09-01T12:00:00.000Z",
  "updatedAt": "2024-09-01T12:00:00.000Z"
}

Keep your userId handy — you’ll need it for all subsequent requests scoped to your account, including character creation.

Create a Character

Create your first roleplay character with POST /v1/users/{userId}/characters. The character starts in draft status and an ID card is generated automatically. You can submit it for staff review once it’s ready.All fields in the request body are required. gender must be either "Masculino" or "Femenino", and bloodType must be one of the eight supported values.Request

curl -X POST https://api.cacolombia.com/v1/users/01J9XK2M4N7P3Q8R5T6W/characters \
  -H "Content-Type: application/json" \
  --cookie "access_token=<your_session_cookie>" \
  -d '{
    "firstNames": "Carlos",
    "lastNames": "Rodríguez",
    "age": 28,
    "height": 175,
    "gender": "Masculino",
    "bloodType": "O+",
    "nationality": "Colombiano",
    "dob": "1996-04-15"
  }'

Response

{
  "userId": "01J9XK2M4N7P3Q8R5T6W",
  "characterId": "01J9XK8P2R4S6T7U9V0W",
  "firstNames": "Carlos",
  "lastNames": "Rodríguez",
  "age": 28,
  "height": 175,
  "gender": "Masculino",
  "bloodType": "O+",
  "nationality": {
    "nombre": "Colombiano",
    "abrev": "COL",
    "lugar": "Colombia"
  },
  "dob": "15/04/1996",
  "avatarHash": null,
  "idCardHash": null,
  "fullBodyHash": null,
  "avatar3dHash": null,
  "avatar3dCamera": null,
  "avatar3dAABB": null,
  "idStatus": "draft",
  "wallet": null,
  "createdAt": "2024-09-01T12:05:00.000Z",
  "updatedAt": "2024-09-01T12:05:00.000Z"
}

Body schema reference

Field	Type	Constraints
`firstNames`	string	Minimum 2 characters
`lastNames`	string	Minimum 2 characters
`age`	number	Integer
`height`	number	In centimetres
`gender`	string	`"Masculino"` or `"Femenino"`
`bloodType`	string	`O+O-A+A-B+B-AB+AB-`
`nationality`	string	Must be a valid nationality name
`dob`	string	ISO 8601 date — `YYYY-MM-DD`

Connect to WebSocket

Connect to the CA Colombia WebSocket server to receive live platform events without polling. After establishing the connection, send a subscribe message to start receiving events for the topics you care about.Connect

const socket = new WebSocket("wss://socket.cacolombia.com/");

socket.addEventListener("open", () => {
  console.log("Connected to CA Colombia WebSocket");

  // Subscribe to character and economy events
  socket.send(JSON.stringify({
    type: "subscribe",
    topics: ["character.update", "wallet.update", "economy.transaction"]
  }));
});

Incoming event example

{
  "type": "wallet.update",
  "characterId": "01J9XK8P2R4S6T7U9V0W",
  "data": {
    "balance": 4500,
    "updatedAt": "2024-09-01T12:10:00.000Z"
  }
}

Handling messages

socket.addEventListener("message", (event) => {
  const payload = JSON.parse(event.data);

  switch (payload.type) {
    case "character.update":
      console.log("Character updated:", payload.characterId);
      break;
    case "wallet.update":
      console.log("New balance:", payload.data.balance);
      break;
    default:
      console.log("Event received:", payload);
  }
});

socket.addEventListener("close", (event) => {
  console.log("Connection closed:", event.code, event.reason);
});

Implement reconnection logic with exponential backoff to handle transient network interruptions gracefully.

What’s Next?

Now that you have a working session and your first character created, explore the full API surface:

Authentication — Understand cookie sessions, token refresh, and error codes in depth.
Character Endpoints — Submit characters for review, update visuals, and manage ID status.
Economy & Banking — Interact with wallets and bank accounts programmatically.
Staff Endpoints — Approve or reject pending character submissions (requires elevated permissions).

Get Started

Core Concepts

Guides

Reference

Get Started with CA Colombia API

What’s Next?

​What’s Next?

What’s Next?