Skip to content

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:

RoleMeaning
INVITEDInvited, but hasn't accepted yet. Grants no access.
MEMBERAccepted member. Can view the organization and its members, and can be given access to single services.
ADMINManages the organization: its details, members, service access and login settings.

Membership lifecycle ​

  1. Create. An admin who creates an organization becomes its ADMIN right away.
  2. Invite. An organization ADMIN invites an existing admin account by email. The account must already exist. TiruPay doesn't create accounts through invites.
  3. Accept or decline. The invited admin sees the invite in their own invite list and accepts (becomes MEMBER) or declines (the invite is deleted).
  4. Change role. An organization ADMIN can switch a member between MEMBER and ADMIN.
  5. Leave or remove. A member can leave, or an organization ADMIN can remove them.

Service access ​

  • Promoting a member to ADMIN gives them access to every service of the organization.
  • A MEMBER gets access to single services when an organization ADMIN links 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.

AreaCovers
catalogueArticles and their availabilities, prices, coupons, balance types, withdrawal rules, referral programs
relationsCustomers, end-users, orders, subscriptions, balances, mandates, withdrawals, consents, bulk emails, GDPR exports and erasure
contentDocuments, files, email templates
analyticsStatistics and reports (not used by any endpoint yet)
systemService settings, service accounts and their API keys, webhooks, payment, email and dunning settings, imports, tax export, logs
LevelAllows
readReading
readwriteReading, creating and updating
readwritedeleteEverything, 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 gets read in every area.
  • Promoting a member to ADMIN links them to the services they didn't have yet, with read in every area. Existing links keep their permissions.
  • PUT /admin/organizations/{organization_id}/services/{service_id}/admins/{user_id}/scopes with {"scopes": [...]} replaces an admin's permissions for that service. It returns the stored permissions: per area only the highest level, plus catalogue: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 403 or 404.
  • 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 ​

FieldTypeDescription
idstringUnique identifier
namestringPublic name (1–255 characters)
slugstringUnique short code (max. 20 characters), used in the organization's branded login URL
colorstring | nullBrand color in HEX, e.g. #1A2B3C
homepagestring | nullHomepage URL
internal_emailstringWhere TiruPay reaches the organization's admins
support_emailstringWhere end-users reach the organization
phonestring | nullPhone number
street, postal_code, citystringPostal address
country_codestringISO 3166-1 alpha-2, e.g. DE
tax_idstring | nullTax ID
logo_file_idstring | nullID of an uploaded logo file
my_rolestring | nullThe caller's own role in this organization (read-only)
created_at, updated_atdatetimeTimestamps

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.

FieldTypeDescription
login_methodPASSWORD | OIDC | SAMLThe login method offered next to the password. SAML is not available yet.
enforce_login_methodbooleanIf 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_2fabooleanAdmins must pass a second factor on every login.
allow_auto_provisioningbooleanThe identity provider may create new admin accounts, and existing admins may join without an invite (see Account linking).
oidc_client_idstring | nullClient ID registered at your identity provider. Required for OIDC.
oidc_client_secretstringClient secret. Required for OIDC. Write-only, never returned.
has_oidc_client_secretbooleanRead-only. Whether a client secret is stored.
oidc_discovery_urlstring | nullThe provider's .well-known/openid-configuration URL. Required for OIDC.
oidc_scopesstring | nullSpace-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:

FieldTypeDescription
password_allowedbooleanWhether to offer password login
organizationsarrayThe 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 400 and 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/password with current_password and new_password. An account without a password (for example one created through an identity provider) leaves out current_password to set its first one.
  • Reset: POST /admin/users/password-reset/request with {"email": "..."} emails a reset link. It answers 202. The link is valid for 15 minutes and works once. The page it opens sends the link's token and a new_password to POST /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/callback

The 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.

  1. Start. The browser opens GET /organizations/{organization_id}/oidc/start and is redirected to the identity provider. An optional login_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.

  2. Callback. The identity provider redirects back to the callback URL. TiruPay decides one of four outcomes:

    OutcomeWhat happens next
    Logged inRedirect to the organization's login page with a one-time code
    2FA neededRedirect with a pending_totp_id and email_fallback flag, see Two-factor authentication
    Confirmation neededRedirect with a pending_link_id, see Account linking
    RejectedRedirect with an error parameter
  3. Exchange. The one-time code is exchanged for an access token at POST /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 loginResult
The email matches no admin account, allow_auto_provisioning is onA new admin account is created (email already verified) and joins the organization as MEMBER.
The email matches no admin account, auto-provisioning is offRejected.
The email matches an existing admin accountConfirmation needed, even if the admin is invited or already a member.
Existing account without membership or invite, auto-provisioning is offRejected.

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:

  1. The admin logs in with a method that already works for them: a password, or another organization's identity provider.
  2. The waiting request shows up in GET /admin/organizations/pending-links (in the TiruPay admin UI: the account security page) for 15 minutes.
  3. 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:

EndpointDescription
POST /admin/users/totp/setupStart 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/enableConfirm setup with the app's current code, within 15 minutes of starting it.
POST /admin/users/totp/disableTurn 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 totp fails with 400 and sends the email. The admin then repeats the login with the code in the totp field.
  • OIDC login: the callback sends the email itself and returns email_fallback=1. The admin submits the code to POST /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 ​

MethodPathDescription
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-optionsLogin methods for an email, no authentication (see Finding the login methods for an email)

Members and invites ​

MethodPathDescription
GET/admin/organizations/{organization_id}/membersList members, including pending invites
POST/admin/organizations/{organization_id}/inviteInvite 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/invitesThe caller's own pending invites
POST/admin/organizations/{organization_id}/acceptAccept an invite
POST/admin/organizations/{organization_id}/declineDecline an invite
POST/admin/organizations/{organization_id}/leaveLeave the organization

Service access ​

MethodPathDescription
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}/scopesReplace 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 ​

MethodPathDescription
GET/admin/organizations/{organization_id}/admin-auth-settingsRead login settings (organization ADMIN)
PUT/admin/organizations/{organization_id}/admin-auth-settingsCreate or partly update login settings (organization ADMIN)
GET/admin/organizations/identitiesThe 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-linksThe caller's identity provider logins waiting for confirmation: organization, resolved_email, expires_at
POST/admin/organizations/pending-links/{pending_link_id}/confirmLink a waiting identity provider login to the caller's account
POST/admin/organizations/pending-links/{pending_link_id}/declineReject a waiting identity provider login
GET/organizations/{organization_id}/oidc/startStart an OIDC login (browser navigation)
GET/organizations/{organization_id}/oidc/callbackCallback from the identity provider
POST/organizations/{organization_id}/oidc/codeExchange the one-time code for an access token
POST/organizations/{organization_id}/oidc/totpFinish an OIDC login that needs 2FA
POST/organizations/{organization_id}/oidc/confirm-linkConfirm linking an identity provider login to an existing account (needs an access token)

Password ​

MethodPathDescription
POST/admin/users/passwordChange the caller's own password, or set a first one
POST/admin/users/password-reset/requestRequest a reset link by email, no authentication
POST/admin/users/password-reset/confirmSet 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.