Developers
Developer guide
Connect your systems and AI assistants to TINIUN: the REST API, OAuth, API keys, webhooks and an MCP server. Start here to choose between OAuth and API keys.
Read workforce data, react to events as they happen, and record what your agents did in your help desk or CRM. One set of scopes controls access whichever way you connect.
What you can build
- REST API (reference): people, teams, live status, schedules, adherence, exceptions, leave and customer interactions.
- Webhooks (guide): signed events when status changes, breaks overrun, exceptions open, schedules publish or interactions arrive.
- MCP server (guide): lets AI assistants such as Claude ask questions about your floor with the asking person’s own access.
- Ready-made integrations (guide): Zendesk, Intercom, HubSpot and anything that can send a webhook, logging replied tickets and answered calls per agent.
OAuth or API key?
Both are supported. Prefer OAuth whenever a person is involved: the app acts as that person, can only see what they can see, tokens expire, and anyone can be disconnected without touching anything else. Use an API key for a server or script you run yourself with no person in the loop.
| OAuth 2.1 (recommended) | API key | |
|---|---|---|
| Acts as | The person who approved it, with their team scope | Your organization (a service), across all teams |
| Access limited by | The approved scopes and the person’s own permissions | The scopes chosen when the key was created |
| Lifetime | Access token 1 hour; refresh token 30 days, rotated on every use | Until it expires (30 days to a year; never, unless your organization requires expiry) or is revoked |
| Best for | AI assistants and MCP clients, apps people sign in to, dashboards | Scheduled jobs, data-warehouse syncs, server-to-server automation |
| Revoke | Per person and application, by an admin | Per key, by an admin |
| Where to create | The application registers itself, or an admin registers it | Settings → Integrations → API keys |
Why OAuth first
Quick start
Create a key
An organization admin opens Settings → Integrations → API keys, picks a name and scopes (for examplepeople:read), and copies the key. It starts withspk_and is shown once.Make a call
Send it as a bearer token.Or use OAuth
If a person is involved, skip the key: register an application and send them through the authorization-code flow. A confidential application acting as itself can useclient_credentialsinstead.
curl https://tiniun.com/api/v1/me \
-H "Authorization: Bearer spk_your_key_here"curl "https://tiniun.com/api/v1/people?limit=100" \
-H "Authorization: Bearer spk_your_key_here"curl "https://tiniun.com/api/v1/people?limit=100" \
-H "Authorization: Bearer spo_your_access_token"curl https://tiniun.com/api/v1/interactions \
-H "Authorization: Bearer spk_your_key_here" \
-H "Idempotency-Key: 6f1c2a9e-call-1042" \
-H "Content-Type: application/json" \
-d '{ "interactions": [{ "agent": { "email": "[email protected]" }, "source": "phones",
"kind": "call_answered", "externalId": "CALL-1042", "occurredAt": "2026-10-07T09:14:00+08:00" }] }'Base URL, versions and limits
- Base URL:
https://tiniun.com/api. The path starts with/v1. Changes within v1 are additive; the date-basedTiniun-Versionheader and the changelog tell you about anything else. The current version is2026-10-11. - Format: JSON in and out. Times are ISO 8601; dates are
YYYY-MM-DDin your organization’s time zone. - Rate limit: per credential, per minute (see rate limits). Every response carries
RateLimit-Limit,RateLimit-RemainingandRateLimit-Reset; over the limit you get429withRetry-Afterseconds. - Errors:
application/problem+jsonwith a stablecodeand arequestId. Branch oncode, not the message. See errors. - Machine-readable spec: /api/v1/openapi.json (OpenAPI 3.1), served from the same definitions as this documentation. It covers every endpoint, the schemas, the error model, both security schemes and the rate-limit headers.
- Request IDs: every response includes
X-Request-Id; send your own to correlate calls, and quote it when you contact support.
Where to read next
- Authentication and scopes: keys, OAuth, client credentials, rotation and network restrictions.
- API reference and conventions: pagination, errors, rate limits, idempotency and versions.
- Webhooks and the MCP server.
- Security best practices and the changelog.
See it with your own scenarios
A 30-minute walkthrough with our team, tailored to your operation.
Book a demo
