Developers
Authentication and scopes
API keys, the OAuth 2.1 authorization-code flow with PKCE, refresh tokens, dynamic client registration and the scopes that control access.
Scopes
A scope names one kind of data. A credential can only call endpoints whose scope it holds. An API key also gets exactly the in-app permissions its scopes imply; an OAuth token additionally never exceeds the permissions of the person who approved it.
| Scope | Lets the holder | Needs permission |
|---|---|---|
| people:read | Names, work email, title, team and status of people, and the list of teams. | team.view, user.view |
| status:read | Who is working, on break or offline right now, and since when. | team.view |
| schedules:read | Published schedules and their shifts, with breaks and meals. | team.view, schedule.view.team |
| adherence:read | Daily scheduled, actual, productive and adherent time per agent. | team.view, adherence.view.team, performance.view.team |
| exceptions:read | Late logins, break overages and other recorded deviations. | team.view, exception.view |
| leave:read | Time-off requests and their status. | team.view |
| interactions:read | The log of tickets replied to, conversations handled and calls answered. | team.view |
| interactions:write | Send tickets, conversations and calls handled by agents into TINIUN. | team.view |
| holidays:read | The organization’s holiday calendar. | team.view |
| forecast:read | Forecast volume and the agents required per queue and interval, against who is scheduled. | team.view, schedule.view.team |
| advisor:read | Coverage gaps and burnout risk counts for the teams the credential can see. No individual-level data. | team.view |
OAuth adds offline_access: Keep access until the person or an admin revokes it, without asking again.
API keys
Send the key as Authorization: Bearer spk_…. Keys are stored only as a hash: TINIUN can’t show a lost key again, only replace it. A key acts across every team in the organization. Each key records when and from where it was last used. Keys are random 192-bit secrets that start with spk_ (so secret scanners can spot a leaked one); TINIUN stores only their SHA-256 and finds them through that hash.
Key expiry, networks and rotation
Under Settings → Integrations → API keys an admin can set, per key:
- Expiry: 30 days, 90 days or a year (or never). An organization can require expiry and cap how long a key may live; new keys then can’t exceed it.
- Allowed networks: addresses or CIDR ranges (IPv4 and IPv6). A key used from anywhere else is refused with
403 IP_NOT_ALLOWEDand the attempt is not counted as a use. Behind a proxy TINIUN uses the client address the platform reports. - Calls per minute: a limit lower than the organization’s, for a key that should never run hot. It can’t raise the organization’s limit.
Replace a key without downtime with Replace (or POST /admin/api-keys/:id/rotate): a new key is created with the same scopes, networks and limit, and the old key keeps working for the overlap you choose (0 to 30 days, 7 by default) and then expires by itself. If the replacement is given more scopes than the old key, the response lists them as warnings so a widening is a decision, not an accident. Scopes of an existing key can’t be edited; that is deliberate.
OAuth 2.1
TINIUN is an OAuth 2.1 authorization server: authorization code with PKCE (S256, required), no implicit or password grants, exact redirect-URI matching, single-use codes and rotating refresh tokens. Discovery documents:
- /.well-known/oauth-authorization-server (RFC 8414)
- /.well-known/oauth-protected-resource (RFC 9728)
| Endpoint | URL |
|---|---|
| Authorization (browser) | https://tiniun.com/oauth/authorize |
| Token | https://tiniun.com/api/oauth/token |
| Revocation (RFC 7009) | https://tiniun.com/api/oauth/revoke |
| Introspection (RFC 7662) | https://tiniun.com/api/oauth/introspect |
| Dynamic registration (RFC 7591) | https://tiniun.com/api/oauth/register |
The authorization-code flow
Create a PKCE pair
Make a randomcode_verifier(43–128 URL-safe characters) and itscode_challenge: base64url of the SHA-256 of the verifier.Send the person to TINIUN
They sign in (if needed), choose the organization, review the scopes and approve or deny.Receive the code
TINIUN redirects to yourredirect_uriwithcode, yourstateandiss. Checkstatematches. A code works once and expires after 60 seconds.Exchange it
POST the code and the verifier to the token endpoint.
https://tiniun.com/oauth/authorize?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&scope=people%3Aread%20status%3Aread%20offline_access
&state=RANDOM_STATE
&code_challenge=BASE64URL_SHA256_OF_VERIFIER
&code_challenge_method=S256curl https://tiniun.com/api/oauth/token \
-d grant_type=authorization_code \
-d code=THE_CODE \
-d redirect_uri=https://app.example.com/callback \
-d client_id=YOUR_CLIENT_ID \
-d code_verifier=YOUR_VERIFIER{
"access_token": "spo_…",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "spr_…",
"scope": "people:read status:read offline_access"
}Confidential clients registered by an admin also send client_secret (in the body, or as HTTP Basic). Public clients (browser, desktop and mobile apps, MCP clients) send none and rely on PKCE. Redirect URIs must be HTTPS, except http://localhost and http://127.0.0.1 for native apps (any port); custom schemes such as myapp:// are allowed for desktop apps.
Client credentials
A confidential application registered by an admin (it has a client_secret) can get a token that acts as the application itself, not a person: like an API key, but short-lived and revocable. Ask only for the scopes you need. No refresh token is issued; ask again when it expires.
curl https://tiniun.com/api/oauth/token \
-u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
-d grant_type=client_credentials \
-d "scope=people:read status:read"Note
Refreshing, revoking and introspecting
Access tokens last one hour. If offline_access was approved you also get a refresh token, valid for 30 days and replaced on every use:
curl https://tiniun.com/api/oauth/token \
-d grant_type=refresh_token \
-d refresh_token=spr_… \
-d client_id=YOUR_CLIENT_IDSecurity
Revoke with POST /oauth/revoke (token, client_id). Organization admins can also end any authorization under Settings → Integrations → OAuth applications, which stops the access token and refresh token immediately.
A resource server or a script can check a token with POST /oauth/introspect (RFC 7662; a confidential client authenticates with its secret). The answer is { "active": true, "scope": "…", … } or just { "active": false } for anything invalid, expired or revoked.
Registering an application
- Self-registration (dynamic): POST
client_nameandredirect_uristo/oauth/register. Only public clients can register this way. People see a notice on the consent screen that the application registered itself and where it will send them back. This is what MCP clients use. - Admin-registered: an organization admin registers an application under Settings → Integrations → OAuth applications, optionally confidential with a client secret. It can only be used within that organization.
Authentication errors
| Status | Meaning |
|---|---|
401 | No credential, or it is invalid, expired or revoked. The response carries a WWW-Authenticate header with a resource_metadata link (RFC 9728) pointing at the discovery document, and error="invalid_token" when a credential was sent. |
403 INSUFFICIENT_SCOPE | The credential is valid but lacks the scope the endpoint needs (the body names it, and WWW-Authenticate carries error="insufficient_scope" and the scope). |
403 IP_NOT_ALLOWED | The API key is restricted to certain networks and this address is not one of them. |
429 | Rate limit exceeded; wait Retry-After seconds. |
400 invalid_grant | (token endpoint) wrong or reused code or refresh token, wrong PKCE verifier or redirect URI. |
401 invalid_client | (token endpoint) unknown client or wrong client secret. |
See it with your own scenarios
A 30-minute walkthrough with our team, tailored to your operation.
Book a demo
