Appearance
User Roles & Permissions
Every account in TiruPay is a user. There are three kinds, and each one logs in differently and sees different data:
| Account | Purpose |
|---|---|
| User | End-user of your application. Sees their own data through linked customers. |
| Service | Service account (API client). Manages one service from your backend. |
| Admin | Person who manages one or more services, e.g. in the TiruPay admin UI. |
User
Users are the end-users of your application. They authenticate via JWT token exchange or OIDC and are created automatically on first login.
Users don't interact with services directly - they access TiruPay through their linked customers. A user can be linked to multiple customers across different services.
Example
An employee logs into your SaaS product. Your backend signs a JWT and exchanges it with TiruPay, which auto-creates a User account. You then link that user to Company A's customer record. The user can now view Company A's orders, balances, and subscriptions.
Service
A service account is an automated API client that represents your application. Each service account is linked to exactly one service and can manage all data within it.
Service accounts use the /me shortcut endpoints to access their own service without needing to know the service ID.
Service Accounts Are Not End-Users
Service accounts authenticate with an API key (not JWT exchange). They are meant for backend-to-backend communication, not for end-user access.
Admin
Admins manage one or more services. They get access to a service through their membership in the service's organization, and only see data of the services they are linked to.
What an admin may do on each service is set by their permissions, e.g. read-only access to customers but full access to the catalogue. Requests outside these permissions fail.
Authentication
Admin login
Admins log in with email and password, or through their organization's identity provider. Organizations can require two-factor authentication. See Organizations & Admin Login.
Password login needs a verified email address; otherwise it fails with 403.
Service Account API Keys
Service accounts authenticate with a long-lived API key, issued by an admin via POST /admin/users/{user_id}/new_token. Send it as a Bearer token on every request.
- Lifetime: 180 days by default
- Rotation: Issuing a new key immediately invalidates the previous one
- Expiry warning: A notification email is sent to service admins 14 days before the key expires
Issuing a key needs the system:readwritedelete permission for the service.
Keep API Keys Secret
An API key grants full programmatic access to the linked service. Rotate it immediately if it is ever exposed.
JWT Token Exchange
User accounts log in via a two-step JWT token exchange initiated by your backend.
Step 1 — Backend exchanges the JWT for an auth code
Your backend signs a JWT with the shared secret configured in the service's Login Information and calls:
POST /identity/token/exchangeTiruPay verifies the signature, finds or creates the User account, and returns a short-lived auth code (valid for 240 seconds):
json
{ "code": "...", "user_id": "...", "service_id": "...", "expires_in": 240 }Step 2 — Backend redirects the user to the TiruPay frontend
Your backend redirects the user's browser to:
/user/{service_id}/provisioning?code={code}&redirect={destination}redirect is the TiruPay-internal frontend path the user should land on after authentication, for example /orders/abc123 or /checkout.
Step 3 — TiruPay frontend exchanges the code for a TiruPay JWT
The /provisioning page calls POST /identity/token/code?code={code} and receives the TiruPay access token.
Step 4 — TiruPay frontend redirects the user
The user is navigated to the path specified in redirect.
The external JWT must contain these claims:
| Claim | Required | Description |
|---|---|---|
sub | Yes | Unique identifier for the user in your system |
email | Yes | User's email address |
first_name | Yes | First name |
last_name | Yes | Last name |
customer_ids | No | List of TiruPay customer IDs to link the user to |
The sub claim is stored as the unique_partner_id and used to identify the user on subsequent logins. This ID is unique per service — the same external user can have different TiruPay User accounts across services.
Auto-Creation
Users are created automatically on their first JWT exchange. No manual user creation is needed for end-users.
OIDC Login
User accounts can also log in via OpenID Connect when the service has OIDC configured.
Step 1 — Start the login
The user's browser navigates to:
GET /identity/oidc/{service_id}/start?redirect_url={destination}TiruPay redirects the browser to the identity provider's login page, using the authorization code flow with PKCE.
redirect_url is checked
destination can be a path relative to the TiruPay frontend, or a full URL on your service's whitelisted domain - see Redirect Security. Anything else is rejected.
Step 2 — Provider authenticates the user
The OIDC provider handles login (username/password, SSO, MFA — whatever it supports), then redirects the browser back to TiruPay at:
GET /identity/oidc/{service_id}/login?code=...&state=...Step 3 — TiruPay validates and exchanges
TiruPay checks the state, exchanges the authorization code for tokens, validates the id_token (signature, audience, issuer, expiry and nonce), reads the user from its claims and the provider's userinfo endpoint (if offered), and finds or creates the User account. The sub claim from the provider is stored as the unique_partner_id.
Step 4 — Redirect to frontend
TiruPay redirects to:
/user/{service_id}/provisioning?code={code}&redirect={destination}This is the same auth code flow as JWT Token Exchange: the frontend exchanges the code for a TiruPay JWT by calling POST /identity/token/code?code={code}, then navigates the user to {destination}.
Configuring OIDC
OIDC must be enabled per service via Login Information. Required settings: discovery_url, client_id, client_secret. Field mappings for email, first_name, last_name, and customer_ids are configurable if the provider uses non-standard claim names.
Linking Users to Services
Every account is linked to at least one service. The link includes a unique_partner_id - the user's identifier in the external system.
- User accounts are linked automatically during JWT exchange.
- Service accounts can only be linked to one service.
- Admin accounts can be linked to multiple services, each with its own permissions.
Linking Users to Customers
Users can be linked to customers to give them access to that customer's data. The user and customer must belong to the same service.
- Linking gives the user read access to the customer's orders, balances, and subscriptions.
- Unlinking removes access but does not delete the user or customer.
- A user can be linked to multiple customers (even across services).
Good to know
Limited User View
Users see simplified versions of resources - no timestamps, no service IDs, no internal details. Service accounts and admins see full details.
Email Uniqueness
User email addresses are globally unique across the entire platform, unlike customer emails which are unique per service.
Service Account Creation
The recommended way to create a service is via the combined endpoint that creates both the service and its service account in one step.
Deleting Users Across Services
If an admin deletes a user who is also linked to services the admin doesn't manage, the user is only unlinked from the admin's services - not deleted.
Relationships
- Services - Users are linked to services via service mappings.
- Organizations - Admins get access to services and their permissions through organizations.
- Customers - Users can be linked to customers for data access.
- Orders - Users access orders through their linked customers.
- Redirect Security - The OIDC login flow's
redirect_urlis validated against your service's whitelist.