Getting Started With the Ownli API

Obtain meaningful customer data by, get this... just asking. Ownli is a personal-data marketplace that allows you to attract, retain, and engage directly with potential and existing customers.

Example applications

The fastest way to try the Ownli API is the ownli-quickstart repo. It contains two runnable apps that together mirror the production integration pattern — admin credentials stay on the server, the browser only sees a short-lived user-scope token:

Subfolder	Stack	What it does
quickstart-server	Node + Express + TypeScript	Proxy that holds admin credentials server-side, mints user-scope JWTs for the browser, and seeds a demo vehicle for the test user.
react-quickstart	Vite + React + TypeScript	Browser app that exercises the full check-in workflow: mileage, condition, and proof-of-address check-ins, plus rewards and payouts.

Clone the repo, drop your clientId, clientSecret, partnerId, and a test userId into the two .env files, and run both apps locally. Full setup instructions are in the repo's README.

Authentication

To use the Ownli API, you'll need API credentials (partnerId, clientId, and clientSecret). Reach out to us at support@ownli.co to request your credentials.

JWT Authentication (Recommended)

Ownli uses JWT (JSON Web Token) Bearer authentication. Instead of sending your credentials with every request, you exchange them once for a short-lived access token and then use that token for all subsequent calls.

Step 1: Obtain a token

curl -X POST https://api.sandbox.ownli.app/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "partnerId": "your-partner-id",
    "scope": "admin"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "partner_id": "your-partner-id",
  "scope": "admin"
}

Step 2: Use the token

Include the access_token in the Authorization header of every API request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Tokens expire after 1 hour. When a token expires, request a new one from the token endpoint.

Token Scopes

The scope field is required when requesting a token. It controls what the token can access:

Scope	Purpose	Use from
admin	Full access to all endpoints including user creation, listing, and bulk operations	Your backend server only
user	Restricted access — cannot list all users, create users, or access admin endpoints	Your mobile or web app

Admin tokens must stay on your server

Never pass an admin token to a mobile or web app. Admin tokens can list all users and access all data for your organization. Use user scoped tokens for any client-side access.

Endpoints that require an admin token are marked with "Admin Token Required" in the API reference. If a user scoped token attempts to access an admin endpoint, the API returns 403 Forbidden:

{
  "error_code": "INSUFFICIENT_SCOPE",
  "error_message": "This endpoint requires an admin token"
}

Legacy Header Authentication (Deprecated)

warning

Legacy header authentication is deprecated and will be removed in a future release. Please migrate to JWT Bearer authentication.

The legacy method passes credentials as headers on every request:

• partnerId — Your partner ID
• clientId — Your client ID
• clientSecret — Your client secret

This method still works but sends your secret on every request. JWT authentication is more secure because your credentials are only transmitted once.