Quickstart

This walkthrough takes you from zero to your first authenticated request against staging (https://api.roja.dev). Swap in https://api.getroja.com when you move to production.

Create an account

Register through the Roja app, or directly against the API with POST /v1/auth/register. You'll need to complete KYC verification before you can create tickets or move money.

Exchange your credentials for a JWT access token:

cURL
JavaScript
Go

curl -X POST https://api.roja.dev/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "08123456789",
    "password": "your-password"
  }'

const res = await fetch("https://api.roja.dev/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    identifier: "08123456789",
    password: "your-password",
  }),
});
const { access_token, refresh_token, twofa_required } = await res.json();

body := strings.NewReader(`{
  "identifier": "08123456789",
  "password": "your-password"
}`)
res, err := http.Post(
  "https://api.roja.dev/v1/auth/login",
  "application/json",
  body,
)

A successful response returns your tokens:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "def50200ab...",
  "expires_at": "2026-07-09T12:00:00Z",
  "twofa_required": false
}

If twofa_required is true, the returned token is temporary — complete the challenge with POST /v1/auth/2fa/verify first. See Authentication.

Make your first call

Browse the ticket marketplace with your access token:

curl https://api.roja.dev/v1/tickets?type=lend&page=1&limit=20 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Create something

Write endpoints that move money require an X-Idempotency-Key header so retries are safe. Create a lend ticket:

curl -X POST https://api.roja.dev/v1/tickets \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "type": "lend",
    "ticket_name": "Short-term business loan",
    "principal_amount": 100000,
    "currency": "NGN",
    "number_of_installments": 3,
    "has_reward": true,
    "reward_amount": 5000,
    "total_amount": 105000
  }'

Next steps

Understand tickets

Offers, matching and the full ticket lifecycle.

Handle errors

The error envelope and every status code we return.

Next steps​

Next steps