Okouro exposes a JSON REST API. Everything the web app can do, your own integrations can do too: manage people, track time, run missions, move deals through the pipeline, and read KPIs. This guide explains how to use the API and how to accomplish common tasks with it. For the exhaustive list of endpoints and their schemas, use the interactive API Reference.

Base URL

Every endpoint is addressed from a single base URL, with no /api prefix:

https://api.okouro.com

When running Okouro locally, the base URL is http://localhost:8080. All examples in this guide use https://api.okouro.com; swap in your own host (or the local one) as needed.

Content type

Request and response bodies are JSON. Send and expect application/json:

Content-Type: application/json

The one exception is the quote PDF download, which returns application/pdf.

Authentication in one line

All endpoints except a small public set require a bearer token in the Authorization header:

GET /auth/me HTTP/1.1
Authorization: Bearer <access_token>

See Authentication for how to obtain and refresh that token.

A first call

Log in, then read your own profile:

POST /auth/login HTTP/1.1
Content-Type: application/json

{
  "email": "you@company.com",
  "password": "your-password"
}

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "user": {
    "id": "0190a1c2-3d4e-7f80-9a1b-2c3d4e5f6a7b",
    "account_id": "0190a1c2-0000-7f80-9a1b-2c3d4e5f6a7b",
    "email": "you@company.com",
    "first_name": "Alex",
    "last_name": "Martin",
    "role": "admin",
    "created_at": "2026-01-05T09:00:00Z",
    "consultant_id": null,
    "settings": { "language": "en" },
    "is_manager": false
  }
}

Use the returned access_token on the next call:

GET /auth/me HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

What is public

Only these routes work without a token: POST /auth/signup, POST /auth/complete-signup, POST /auth/login, POST /auth/refresh, POST /invitations/accept, POST /password-changes/redeem, GET /health, and GET /openapi.json. Everything else returns 401 Unauthorized without a valid bearer token.

How this guide is organised

• Getting started covers the ground rules: this overview, Authentication, and Roles and permissions.
• Using the API covers cross-cutting behaviour: Conventions (ids, dates, money, pagination), Errors, and Rate limits.
• Guides are task walkthroughs that chain several endpoints in order: Manage people, Track time, Request time off, Manage expenses, Run a mission, Sales pipeline, and Read KPIs.

Where the numbers come from

Every request and response in this guide reflects the live API contract, which is published as an OpenAPI 3.1 document at GET /openapi.json and rendered in the API Reference. When a guide and the reference disagree, the reference wins.