Teams: organisations, roles and invitations
An organisation is one Sortance account shared by a team. Its API keys, configuration, traces and monthly quota belong to the organisation, not to whoever created them, so they keep working when people come and go.
Organisations
- Signing in for the first time creates a personal organisation with you as its owner. You can create more from the organisation menu at the top of the dashboard sidebar; you can own up to 10.
- You can belong to any number of organisations. The dashboard works on one at a time: the active organisation, shown in the sidebar. Switching reloads the dashboard, and the key this browser uses moves to the new organisation with it.
- Everything a key does is recorded against its organisation. Every member sees the same traces, the same configuration and the same usage meter. Quota and rate limits are per organisation, across all of its keys, including revoked ones.
- Each organisation has exactly one owner. Ownership moves only by transfer, from the Org settings tab of Settings → Team; the old owner becomes an admin.
Roles
Four roles, each including everything below it. The same table decides what the dashboard shows you and what the server allows; hiding a button is a convenience, the refusal happens on the server.
| Can | viewer | member | admin | owner |
|---|---|---|---|---|
| Read dashboards, traces, screenings, usage and every configuration screen | ✓ | ✓ | ✓ | ✓ |
| Run checks (verify, decide, enrich, screen, check), upload and run bulk verification jobs, and report outcomes and events | — | ✓ | ✓ | ✓ |
| Change policies (the Email types switches included), lists, ICP rubrics, experiments, and domain and address rules; block a bulk job's addresses | — | ✓ | ✓ | ✓ |
| Connect and disconnect Stripe and RB2B | — | — | ✓ | ✓ |
| Create API keys and revoke any key of the organisation | — | — | ✓ | ✓ |
| Invite people, resend and revoke invitations | — | — | ✓ | ✓ |
| Change roles and remove members | — | — | ✓ | ✓ |
| Rename the organisation | — | — | ✓ | ✓ |
| Transfer ownership to another member | — | — | — | ✓ |
| Delete the organisation | — | — | — | ✓ |
Two rules on top of the table:
- Admins act on members and viewers. An admin may invite, promote (as far as admin), demote and remove members and viewers. Only the owner changes or removes an admin. Nobody changes their own role.
- Anyone but the owner may leave. Leaving revokes your browser keys, the API keys you created and the invitations you sent in that organisation. The owner transfers ownership first. An owner who is the only member, with no pending invitations, may delete the organisation.
Invitations
- Admins and the owner invite by email from the Team screen, choosing admin, member or viewer. The invitation is emailed; the link is not shown in the dashboard.
- An invitation is bound to the address it was sent to. Opening the link shows who it is for, with the address masked; to accept, the person signs in with that address (signing in creates an account if they have none) and presses Accept. Anyone else holding the link cannot use it.
- Opening the link never uses it up. Only the Accept button does, so mail scanners that prefetch links cannot consume an invitation.
- Invitations last 7 days. Resend issues a fresh link and kills the old one; revoke kills it outright. Inviting the same address again replaces the earlier invitation.
- An organisation has 25 seats, and pending invitations count toward them. Revoke an invitation or remove someone to free one.
API keys and their roles
Every API key belongs to an organisation and carries a role of its own: admin, member or viewer. The API checks the key’s role on every request, before anything is metered.
- Admins create keys on the API keys screen and pick the role. A key never carries more access than the person who made it; an owner’s keys are admin keys, because ownership actions are dashboard-only. An organisation can hold 25 live keys made this way.
- The dashboard also gives each browser you sign in on a key of its own, at your role, up to 3 per person per organisation. These are marked
auto. When your role changes, they follow it. - When a member’s role is lowered, keys they created are lowered to match; they are never raised. When someone is removed, their browser keys and pending invitations are revoked, and so are the keys they created unless the admin chooses to keep them (someone who leaves always loses the keys they created). Kept keys stay with the organisation, marked creator left.
| Key role | May call | Refused |
|---|---|---|
viewer | GET routes: /v1/traces, /v1/screenings, /v1/usage, /v1/me, policies, lists, experiments, ICP, domain and address rules, bulk jobs and their result files, integration status. POST /v1/addresses/check. MCP initialize, tools/list, and the read-only rules tools get_policy_context and list_blocklist. | Every other POST, PUT, PATCH or DELETE (running a check, uploading or starting a bulk job, changing configuration): 403 forbidden. |
member | Everything a viewer can, plus /v1/verify, /v1/decide, /v1/enrich, /v1/screen, /v1/check, /v1/outcome, /v1/events, bulk jobs (create, upload, start, cancel, resume, delete, block), MCP tools/call, and writes to policies, lists, experiments, ICP, and domain and address rules. | Connecting or disconnecting an integration: 403 forbidden. |
admin | Everything, including POST and DELETE on /v1/integrations/stripe and /v1/integrations/rb2b. | Nothing at the API. Org-level actions (invites, roles, transfer, delete) live in the dashboard only. |
The 403
A call above the key’s role gets 403 forbidden. It is refused before rate limiting and metering, so it costs nothing. The message names only the key’s own role:
curl -X POST https://api.sortance.com/v1/verify \
-H "Authorization: Bearer $VIEWER_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"mia@acme.com"}'
{ "error": { "code": "forbidden",
"message": "This API key's role (viewer) cannot do this. Ask an org admin.",
"trace_id": "..." } }Over MCP, a viewer key can initialize, list tools and call the read-only rules tools get_policy_context and list_blocklist; any other tools/call returns JSON-RPC error -32003 with data.code set to "forbidden". An app connected by signing in (see MCP sign-in) acts as the person who approved it, capped at member, or viewer for read-only access.
Which organisation is this key?
GET /v1/me returns the key’s organisation (id and name) and the key’s own id, role and origin (auto, manual or service). The full error list is in the API reference; quota and rate limits are in Going to production.