Skip to content

User Roles & Permissions ​

Every account in TiruPay is a user. There are three kinds, and each one logs in differently and sees different data:

AccountPurpose
UserEnd-user of your application. Sees their own data through linked customers.
ServiceService account (API client). Manages one service from your backend.
AdminPerson 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/exchange

TiruPay 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:

ClaimRequiredDescription
subYesUnique identifier for the user in your system
emailYesUser's email address
first_nameYesFirst name
last_nameYesLast name
customer_idsNoList 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_url is validated against your service's whitelist.