Sign-in
3 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.
Get sign-in settings for the web app
GET/api/v1/auth/config
- Access
- No authentication.
With app=books, the settings for the Tolvi Books app, which signs business owners in with their own account (no organisation).
Parameters
| Name | In | Type | Description |
|---|---|---|---|
app | query | string (SignInApp) | Which Tolvi app is signing in. Defaults to web (practices). One of: |
Responses
200 OK, application/json
Body: object (AuthConfig).
What the web app needs to start sign-in.
| Field | Type | Description |
|---|---|---|
moderequired | string (AuthMode) | One of: |
issuer | string | OIDC issuer (oidc mode). |
clientId | string | |
audience | stringnullable | |
scope | string | |
signupOpenrequired | boolean | Whether new firms and businesses can sign themselves up. When false, people join only by invitation. |
Errors: 400 Bad request, 429 Too many requests, as problem details (application/problem+json).
Get the signed-in user and their firms
GET/api/v1/me
- Access
- A signed-in Tolvi session only (no scope applies).
Sign-in tokens only, not API tokens.
Responses
200 OK, application/json
Body: object (Me).
| Field | Type | Description |
|---|---|---|
userIdrequired | string (uuid) | |
namerequired | stringnullable | |
emailrequired | string (email) | |
membershipsrequired | array of FirmMembership | |
memberships[].firmIdrequired | string (uuid) | |
memberships[].firmNamerequired | string | |
memberships[].rolerequired | string (MembershipRole) | One of: |
memberships[].staffRolerequired | string (StaffRole)nullable | One of: |
memberships[].tenantKind | string (TenantKind) | practice: an accountancy firm. business: a business in Tolvi Books (a Books-app sign-in lists only these; any other sign-in only practices). One of: |
memberships[].authOrgId | stringnullable | The firm’s identity-provider organisation, if it has one. A practice’s web app signs in through it. |
platformStaff | boolean | True when this person is Tolvi platform staff, so the web app can offer the staff-only pages without asking the staff access check (which refuses everyone else). The internal endpoints still run their own checks, MFA included. |
Errors: 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).
Find out whether you also belong in the other Tolvi app
GET/api/v1/me/other-app
- Access
- A signed-in Tolvi session only (no scope applies).
For the app you signed in to, says whether you are also a member in the other one (Tolvi Books for a business, the Tolvi web app for a practice), and whether an invitation for it is waiting for your verified email address. A yes or no about you, with no firm names or ids. Answers people who have no firm in this app yet. Sign-in tokens from the Tolvi apps only, not API tokens, connected apps or MCP.
Responses
200 OK, application/json
Body: object (OtherApp).
Whether the signed-in person also belongs in the other Tolvi app, for routing after sign-in. A yes or no about their own identity: no firm names, ids or data of the other kind.
| Field | Type | Description |
|---|---|---|
otherApprequired | string (OtherAppKind)nullable | books: they are a member of a business in Tolvi Books. practice: they are a member of an accountancy firm. Null: neither beyond the kind this sign-in reaches. One of: |
otherAppInvitationsrequired | boolean | An invitation of the other kind is waiting for their verified email address. |
otherAppUrlrequired | string | The address of the other app. |
Errors: 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).