Appearance
Organizations & Admin Login
An organization groups the admins and services of one company. Each service belongs to one organization, and an admin works on a service through their membership in that organization. Organizations are for admin accounts only: service accounts and end-users belong to one indirectly, through the service(s) they are connected to.
End-users stay within one organization
An end-user can only be linked to services and customers of one organization. Linking them to a customer of another organization's service fails with 409. Admins aren't limited this way and can work across organizations.
Each organization also decides how its admins log in: with a password, through the organization's own identity provider (OIDC), or both. It can also require two-factor authentication.
Membership
An admin's relationship to an organization has one of three roles:
| Role | Meaning |
|---|---|
INVITED | Invited, but hasn't accepted yet. Grants no access. |
MEMBER | Accepted member. Can view the organization and its members, and can be given access to single services. |
ADMIN | Manages the organization: its details, members, service access and login settings. |
Membership lifecycle
- Create. An admin who creates an organization becomes its
ADMINright away. - Invite. An organization
ADMINinvites an existing admin account by email. The account must already exist. TiruPay doesn't create accounts through invites. - Accept or decline. The invited admin sees the invite in their own invite list and accepts (becomes
MEMBER) or declines (the invite is deleted). - Change role. An organization
ADMINcan switch a member betweenMEMBERandADMIN. - Leave or remove. A member can leave, or an organization
ADMINcan remove them.
Service access
- Promoting a member to
ADMINgives them access to every service of the organization. - A
MEMBERgets access to single services when an organizationADMINlinks them. - Leaving or being removed revokes all access to the organization's services, and unlinks the admin's identity provider login for that organization.
What an admin may do on a service depends on their permissions for it.
The last admin stays
An organization always keeps at least one ADMIN. The only ADMIN can't leave or be demoted. Promote another member first.
Admin permissions
An admin's access to a service is split into areas. For each area, the admin holds one level. Permissions are set per service, so the same admin can have full access to one service and only read access to another. This applies to every admin, including organization ADMINs.
| Area | Covers |
|---|---|
catalogue | Articles and their availabilities, prices, coupons, balance types, withdrawal rules, referral programs |
relations | Customers, end-users, orders, subscriptions, balances, mandates, withdrawals, consents, bulk emails, GDPR exports and erasure |
content | Documents, files, email templates |
analytics | Statistics and reports (not used by any endpoint yet) |
system | Service settings, service accounts and their API keys, webhooks, payment, email and dunning settings, imports, tax export, logs |
| Level | Allows |
|---|---|
read | Reading |
readwrite | Reading, creating and updating |
readwritedelete | Everything, including deleting and other irreversible actions (e.g. terminating, revoking, refunding, rotating keys, unlinking) |
A permission is written as area:level, e.g. relations:readwrite. A higher level includes the lower ones. Every admin linked to a service always holds catalogue:read.
Granting permissions
- Linking a member to a service takes an optional body
{"scopes": [...]}. Without it, the admin getsreadin every area. - Promoting a member to
ADMINlinks them to the services they didn't have yet, withreadin every area. Existing links keep their permissions. PUT /admin/organizations/{organization_id}/services/{service_id}/admins/{user_id}/scopeswith{"scopes": [...]}replaces an admin's permissions for that service. It returns the stored permissions: per area only the highest level, pluscatalogue:read.
An admin reads their own permissions from service_scopes in their profile (GET /admin/identity/validate): a map from service ID to the list of permissions. Use it to hide actions the admin can't perform.
Missing permissions
- A request for a single resource of a service where the admin lacks the permission fails with
403or404. - Lists only contain data from the services where the admin holds the permission. If that is none of their services, the request fails with
403.
Organization fields
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier |
name | string | Public name (1–255 characters) |
slug | string | Unique short code (max. 20 characters), used in the organization's branded login URL |
color | string | null | Brand color in HEX, e.g. #1A2B3C |
homepage | string | null | Homepage URL |
internal_email | string | Where TiruPay reaches the organization's admins |
support_email | string | Where end-users reach the organization |
phone | string | null | Phone number |
street, postal_code, city | string | Postal address |
country_code | string | ISO 3166-1 alpha-2, e.g. DE |
tax_id | string | null | Tax ID |
logo_file_id | string | null | ID of an uploaded logo file |
my_role | string | null | The caller's own role in this organization (read-only) |
created_at, updated_at | datetime | Timestamps |
The public lookup by slug returns only id, name, slug, homepage, color, support_email, logo_file_id and the timestamps, plus two login fields: admin_login_method and admin_login_enforced (see below). A login page can use them to show the right form before the admin enters anything.
Admin login strategy
Login settings
Each organization has one set of login settings. An organization that never saved any settings behaves as PASSWORD, with no enforcement and no 2FA requirement.
| Field | Type | Description |
|---|---|---|
login_method | PASSWORD | OIDC | SAML | The login method offered next to the password. SAML is not available yet. |
enforce_login_method | boolean | If true, login_method is the only way in and password login is turned off for admins who linked their identity provider login. Needs OIDC as login_method. |
enforce_2fa | boolean | Admins must pass a second factor on every login. |
allow_auto_provisioning | boolean | The identity provider may create new admin accounts, and existing admins may join without an invite (see Account linking). |
oidc_client_id | string | null | Client ID registered at your identity provider. Required for OIDC. |
oidc_client_secret | string | Client secret. Required for OIDC. Write-only, never returned. |
has_oidc_client_secret | boolean | Read-only. Whether a client secret is stored. |
oidc_discovery_url | string | null | The provider's .well-known/openid-configuration URL. Required for OIDC. |
oidc_scopes | string | null | Space-separated scopes. Default: openid email profile. |
Switching login_method without the fields that method needs is rejected with 400. Switching back to PASSWORD clears the OIDC fields.
Test before you enforce
Setting up OIDC does not turn off password login. Admins can keep using their password while you check that the identity provider login works. Only set enforce_login_method once that's confirmed. A mistyped client secret on an enforced organization locks out every admin who already linked their login.
Policies apply to the whole account
Login settings apply to an admin's account, not only to logins through that organization's page. An admin can belong to several organizations, and the strictest setting among their accepted memberships wins:
- Password login is turned off if any of these organizations enforces its OIDC login and the admin has linked their identity provider login for it.
- 2FA is required if any of them sets
enforce_2fa.
Pending invites don't count. An admin who is invited to an OIDC-only organization, or is a member but hasn't linked yet, keeps logging in with their password. Password login turns off once they link their identity provider login.
Finding the login methods for an email
A generic login page can ask for the email first and then show only the methods that apply, so admins don't need to know their organization's slug. POST /public/organizations/login-options with {"email": "..."} (no authentication) returns:
| Field | Type | Description |
|---|---|---|
password_allowed | boolean | Whether to offer password login |
organizations | array | The organizations to offer, sorted by name, with the same fields as the public lookup by slug (incl. admin_login_method and admin_login_enforced) |
The endpoint is rate-limited.
Password login
Admins log in at POST /admin/identity/token with email and password, plus a totp field when a second factor is needed.
- If password login is turned off for the account, the request fails with
400and a hint to use the organization's identity provider. - If 2FA is required, see Two-factor authentication.
Changing and resetting the password
- Change: a logged-in admin calls
POST /admin/users/passwordwithcurrent_passwordandnew_password. An account without a password (for example one created through an identity provider) leaves outcurrent_passwordto set its first one. - Reset:
POST /admin/users/password-reset/requestwith{"email": "..."}emails a reset link. It answers202. The link is valid for 15 minutes and works once. The page it opens sends the link'stokenand anew_passwordtoPOST /admin/users/password-reset/confirm.
Both fail with 400 if the new password is too weak, and aren't possible while password login is turned off for the account. A reset doesn't log the admin in, and 2FA still applies at the next login. The reset endpoints are rate-limited.
New passwords need at least 8 characters, a digit, an uppercase and a lowercase letter, and a special character.
OIDC login
Register this redirect URI at your identity provider:
{TIRUPAY_API_URL}/organizations/{organization_id}/oidc/callbackThe flow uses the authorization code flow with PKCE. TiruPay checks the ID token's signature, issuer, audience, expiry and nonce before trusting any claim. The token must contain sub and email; if the email is missing from the ID token, TiruPay fetches it from the provider's userinfo endpoint. The email must be a valid email address, and a login whose email_verified claim is false is rejected.
Start. The browser opens
GET /organizations/{organization_id}/oidc/startand is redirected to the identity provider. An optionallogin_hint(the admin's email) is passed on to the provider so it can pre-fill its login form. The login must be completed within 30 minutes.Callback. The identity provider redirects back to the callback URL. TiruPay decides one of four outcomes:
Outcome What happens next Logged in Redirect to the organization's login page with a one-time code2FA needed Redirect with a pending_totp_idandemail_fallbackflag, see Two-factor authenticationConfirmation needed Redirect with a pending_link_id, see Account linkingRejected Redirect with an errorparameterExchange. The one-time
codeis exchanged for an access token atPOST /organizations/{organization_id}/oidc/code?code=.... The code is valid for 2 minutes and works once.
Pass redirect=false to the callback to get these outcomes as JSON instead of a redirect. In that case a successful login returns the access token directly.
Account linking
The first time an identity provider login arrives, TiruPay has to connect it to an admin account. After that, the provider's subject (sub) is linked to the account, and later logins go straight in, as long as the admin is still an accepted member of the organization.
| Situation on first login | Result |
|---|---|
The email matches no admin account, allow_auto_provisioning is on | A new admin account is created (email already verified) and joins the organization as MEMBER. |
| The email matches no admin account, auto-provisioning is off | Rejected. |
| The email matches an existing admin account | Confirmation needed, even if the admin is invited or already a member. |
| Existing account without membership or invite, auto-provisioning is off | Rejected. |
Why confirmation is always needed: any admin can create an organization and connect an identity provider they control. That provider can claim any email address. An email match alone therefore never proves who owns an existing account. The owner has to prove it:
- The admin logs in with a method that already works for them: a password, or another organization's identity provider.
- The waiting request shows up in
GET /admin/organizations/pending-links(in the TiruPay admin UI: the account security page) for 15 minutes. - The admin confirms it with
POST /admin/organizations/pending-links/{pending_link_id}/confirm. TiruPay links the identity provider login and accepts a pending invite or adds a membership.
Confirming only works in the browser that did the identity provider login. The callback sets an HttpOnly cookie there, so send the list and confirm requests with cookies (credentials: "include"). In the list, confirmable_here shows which request this browser can confirm. From any other browser, confirming answers 403.
An admin who didn't start that login declines it with POST .../decline; it can't be confirmed afterwards. Declining works from any browser. Both calls answer 404 if the request doesn't exist, has expired, was already used, or belongs to a different account.
POST /organizations/{organization_id}/oidc/confirm-link?pending_link_id=... confirms the same way and additionally returns a fresh access token.
Admins without a working login method
Confirming needs an existing way in. An invited admin who never set a password has to set one first before they can link an identity provider login.
Two-factor authentication
Admins set up an authenticator app themselves:
| Endpoint | Description |
|---|---|
POST /admin/users/totp/setup | Start setup. Returns secret and a provisioning_uri (for a QR code). Changes nothing until confirmed, so it's safe to call again, for example to switch devices. |
POST /admin/users/totp/enable | Confirm setup with the app's current code, within 15 minutes of starting it. |
POST /admin/users/totp/disable | Turn off the app with its current code. |
When 2FA is required but the admin hasn't set up an app, TiruPay emails a 6-digit code instead:
- Password login: the first attempt without
totpfails with400and sends the email. The admin then repeats the login with the code in thetotpfield. - OIDC login: the callback sends the email itself and returns
email_fallback=1. The admin submits the code toPOST /organizations/{organization_id}/oidc/totp?pending_totp_id=...&code=.... With an authenticator app set up, the same endpoint takes the app's code.
An emailed code is valid for 10 minutes, works once and allows 5 wrong attempts. A new code can be requested at most once per minute. The OIDC pending_totp_id expires after 10 minutes.
Endpoints
Organizations
| Method | Path | Description |
|---|---|---|
GET | /admin/organizations/ | List the caller's organizations (limit, offset, query search on name and slug) |
GET | /admin/organizations/{organization_id} | Get one organization |
POST | /admin/organizations/ | Create an organization; the caller becomes its ADMIN |
PATCH | /admin/organizations/{organization_id} | Update fields (organization ADMIN) |
GET | /public/organizations/{slug} | Public lookup by slug, no authentication |
POST | /public/organizations/login-options | Login methods for an email, no authentication (see Finding the login methods for an email) |
Members and invites
| Method | Path | Description |
|---|---|---|
GET | /admin/organizations/{organization_id}/members | List members, including pending invites |
POST | /admin/organizations/{organization_id}/invite | Invite an admin by email (organization ADMIN) |
PATCH | /admin/organizations/{organization_id}/members/{user_id} | Set role to MEMBER or ADMIN (organization ADMIN) |
DELETE | /admin/organizations/{organization_id}/members/{user_id} | Remove a member (organization ADMIN) |
GET | /admin/organizations/invites | The caller's own pending invites |
POST | /admin/organizations/{organization_id}/accept | Accept an invite |
POST | /admin/organizations/{organization_id}/decline | Decline an invite |
POST | /admin/organizations/{organization_id}/leave | Leave the organization |
Service access
| Method | Path | Description |
|---|---|---|
POST | /admin/organizations/{organization_id}/services/{service_id}/admins/{user_id} | Give a member access to one of the organization's services, optionally with scopes (organization ADMIN) |
PUT | /admin/organizations/{organization_id}/services/{service_id}/admins/{user_id}/scopes | Replace the member's permissions for that service (organization ADMIN) |
DELETE | /admin/organizations/{organization_id}/services/{service_id}/admins/{user_id} | Revoke that access (organization ADMIN) |
Login settings and OIDC
| Method | Path | Description |
|---|---|---|
GET | /admin/organizations/{organization_id}/admin-auth-settings | Read login settings (organization ADMIN) |
PUT | /admin/organizations/{organization_id}/admin-auth-settings | Create or partly update login settings (organization ADMIN) |
GET | /admin/organizations/identities | The identity provider logins linked to the caller's own account: organization (incl. its current admin_login_method), provider discovery URL, subject and link date |
GET | /admin/organizations/pending-links | The caller's identity provider logins waiting for confirmation: organization, resolved_email, expires_at |
POST | /admin/organizations/pending-links/{pending_link_id}/confirm | Link a waiting identity provider login to the caller's account |
POST | /admin/organizations/pending-links/{pending_link_id}/decline | Reject a waiting identity provider login |
GET | /organizations/{organization_id}/oidc/start | Start an OIDC login (browser navigation) |
GET | /organizations/{organization_id}/oidc/callback | Callback from the identity provider |
POST | /organizations/{organization_id}/oidc/code | Exchange the one-time code for an access token |
POST | /organizations/{organization_id}/oidc/totp | Finish an OIDC login that needs 2FA |
POST | /organizations/{organization_id}/oidc/confirm-link | Confirm linking an identity provider login to an existing account (needs an access token) |
Password
| Method | Path | Description |
|---|---|---|
POST | /admin/users/password | Change the caller's own password, or set a first one |
POST | /admin/users/password-reset/request | Request a reset link by email, no authentication |
POST | /admin/users/password-reset/confirm | Set a new password with a reset link's token, no authentication |
Relationships
- Services: every service belongs to one organization; admin access to a service comes from the membership.
- User Roles & Permissions: the account roles; organization roles only apply to admin accounts.
- Files: the organization logo is an uploaded file.