Olik Split API

Quickstart

Three steps to your first response.

1. 1 Get your secret key

   Provision a secret key from your partner dashboard. It looks like sk_live_... and authenticates the partner / management surface. Keep it server-side — never ship it in a client app.

2. 2 Make your first call

   Check your account usage. A 200 here confirms your key works.

   Copy

   curl https://api.oliksplit.app/v1/usage \
     -H "Authorization: Bearer sk_live_..."

   No key needed for the health check:

   Copy

   curl https://api.oliksplit.app/health

   Response:

   {"status":"ok","version":"..."}

3. 3 Explore

   Browse the endpoint reference below, or pull the machine-readable contract from openapi.yaml / openapi.json.

Authentication

Every request carries a bearer token in the Authorization header. There are two auth modes, and which one you use depends entirely on the path prefix.

Which key for which path

Header format

Both modes use the same scheme — only the token value differs:

Authorization: Bearer <token>

Link token → session exchange

To act on behalf of one of your end-users, mint a session JWT for them:

1. Using your secret key, create a session for the user via POST /v1/sessions. This returns a short-lived link token.
2. Exchange that link token for a session JWT via POST /v1/sessions/exchange.
3. Use the returned JWT as the bearer token for all /v1/data/* calls. Refresh it before expiry with POST /v1/sessions/refresh.

# 1. mint a session for an end-user (secret key)
curl -X POST https://api.oliksplit.app/v1/sessions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"userId":"your-end-user-id"}'

# 2. exchange the returned link token for a session JWT
curl -X POST https://api.oliksplit.app/v1/sessions/exchange \
  -H "Content-Type: application/json" \
  -d '{"linkToken":"lt_..."}'

# 3. call the end-user surface with the JWT
curl https://api.oliksplit.app/v1/data/me \
  -H "Authorization: Bearer <jwt>"

Core concepts

The data model, from the outside in.

Customer (the partner)

That's you — the company integrating Olik Split. Your secret key represents the Customer account. All groups, expenses, and end-users you create belong to your Customer.

End-users

The people inside your app. They can be full accounts or "ghost" users — participants you create with no signup, useful for someone who needs to be in a split but hasn't installed anything. Session JWTs are always scoped to one end-user.

Groups

A shared ledger between end-users — a trip, a household, a project. Every group carries a base currency and a member list. Expenses and balances live inside a group.

Expenses

A charge logged against a group: who paid, how much, in what currency, and how it splits across members (equal, exact amounts, shares, or a saved split preset).

Balances

The running net position of each member, derived from all expenses in the group: who owes whom and by how much, expressed in the group's base currency.

Settlements

Recorded payments that clear debt. The settle-up flow computes the minimal set of transfers to zero out balances; executing a settlement writes those transfers back to the ledger.

Endpoint reference

All paths are relative to https://api.oliksplit.app. The full contract — request/response schemas included — is in the OpenAPI spec.

Sessions secret key

Partner surface secret key

End-user data surface session JWT

All paths under /v1/data/*. Scoped to the end-user the JWT was minted for.

Usage & webhooks secret key

Utility no auth

SDKs

The official Android / Kotlin Multiplatform SDK is in preview. It is not yet published to Maven Central — that's coming soon. Until then, integrate one of two ways:

npx openapi-typescript https://api.oliksplit.app/openapi.json -o olik.ts

Errors

Errors use a uniform JSON envelope and standard HTTP status codes. Every response carries a requestId — quote it when contacting support.

{
  "error": "...",
  "message": "...",
  "requestId": "..."
}

401 Unauthorized shapes

Auth failures are discriminated so you can tell why a request was rejected — by the error field:

Example:

{
  "error": "malformed_key",
  "message": "Authorization header is not a valid API key.",
  "requestId": "req_..."
}

Multi-currency

Each group carries a base currency. Expenses can be logged in any ISO-4217 currency — when an expense currency differs from the group's base currency, the conversion is handled server-side, and balances and settlements are always expressed in the group's base currency.

In short: log expenses in whatever currency they actually occurred in; Olik Split normalizes everything to the group base for you.