Identities and entitlements

Give people and systems the right access

Named users represent the people administering the service or making approval decisions. Machine clients represent the bank systems connected to Quant Flow. Separate identities let the bank attribute activity and revoke one person's or system's access without sharing a login.

A role defines permitted actions. An approval group selects people eligible to decide a task; joining a group does not itself grant other platform permissions. The bank's security and administration teams should review these assignments and keep submission and approval responsibilities separate.

Invite people with the access their work requires, review changes when their duties change and revoke access when it is no longer needed. Coordinate system credentials with the deployment's identity-provider owner. The token claims and permission details below are for administrators and engineers implementing those controls.

A role defines permitted actions

Each named user has an assigned role. That role contains the permissions for the actions the person may perform, such as administering a policy or changing a team member's access.

%%{init: {"theme": "neutral"}}%%
flowchart TB
    Person["Named bank user"] --> Role["Assigned role"]
    Role --> Permissions["Permissions held by that role"]
    Permissions --> Actions["Permitted platform actions"]

The administrator may grant only permissions they hold. Connected bank systems use their own machine identities; they should not share a person's login.

An approval group defines eligible decision-makers

A policy can name a group for sign-off. When the approval task is created, the group resolves to its eligible named members and the platform keeps that snapshot with the task.

%%{init: {"theme": "neutral"}}%%
flowchart TB
    Policy["Configured policy asks for sign-off"] --> Group["Resolve the named approval group"]
    Group --> Task["Create a task for eligible members"]
    Task --> Decision["Assigned person approves or refuses"]
    Decision --> Record["Retain the decision and who acted"]

Group membership does not itself grant platform permissions. The person who initiated the request cannot approve it; use a separate authorised identity. An approval lets the instruction continue, and operations still needs the final token outcome.

View in API Reference

• Read the permission catalogue
• Read approval groups
• Read the approver's tasks

Principals and organisations

Protected requests carry a bearer token. Authentication lists bootstrap operations and endpoint-specific exceptions. The token has two claims that matter:

The organisation is never taken from a path, query parameter or body. Where a path contains an organisation id (for example /api/tenants/{id}/users), it must equal the caller's tenant_id claim, or the request is refused with 403. A resource that belongs to another organisation reads as 404, the same as one that does not exist.

Customer integration users are assigned an organisation. Confirm the supplied token claims and entitlements during onboarding.

There are two kinds of principal:

A machine client is a distinct identity issued by the identity provider. Its client identifier appears in the token as sub, so its activity is attributable in logs and audit records. In a client-hosted deployment the bank registers machine clients in its own identity provider. See Authentication.

Give each integrating system its own client. Separate clients keep activity attributable and let you revoke one system without affecting the others.

Users

An administrator invites a user into their own organisation. The invited user activates their account by setting a password. Removing a user revokes their access and signs them out; the record is kept with status REMOVED. A user cannot remove themselves, and the organisation's owner cannot be removed.

A caller whose status is not ACTIVE receives 401, so a client holding a still-valid token can sign the user out.

Roles and permissions

A permission is a named action in resource:action form, for example policy:read or member:remove. GET /api/permissions returns the full catalog. The catalog is platform reference data, the same for every organisation.

A role grants a set of permissions. There are two kinds:

Each user holds one role. GET /api/users/me returns the caller's role and the flat set of permissions it grants.

No user can grant more than they hold. When you create a custom role, add permissions to one, invite a user onto one, or assign one, you may grant only permissions you hold yourself. Replacing a custom role's permissions is a full replacement: a permission left out is revoked.

Examples of permissions the identity endpoints require:

Use the permission catalogue and the endpoint's documented access checks. Where authentication or permission checks are marked planned in the reference, do not treat those declarations as proof of deployed enforcement; verify access with the operator and your assigned identities.

Approval groups

An approval group is a named set of users that policies route approval tasks to. Each group has a key such as #mlro.

• The key must match ^#[a-z][a-z0-9_]{0,62}$, is unique within the organisation, and cannot be changed after creation. A policy that references a key therefore never re-points to a different group.
• Groups are deactivated, never deleted. A policy that references a deactivated group fails at evaluation, and no approval request is created. It does not fall through to "no approver".
• Members must be ACTIVE or INVITED users in your organisation.
• When a task is created, the group is resolved to its members at that moment. A later change to membership does not change who was asked on existing tasks.

See Policy, approvals and audit.

Worked example

Read the caller's own profile and permissions.

GET /api/users/me HTTP/1.1
Host: api.qfp.quantnetwork.net
Authorization: Bearer <access token>
API-Version: 1.0.0

Illustrative example built from the schema.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "8f14e45f-ceea-467a-9a1e-1c8b4b0b5a21",
  "firstName": "Priya",
  "lastName": "Raman",
  "email": "[email protected]",
  "tenantId": "11111111-1111-1111-1111-111111111111",
  "role": "ADMIN",
  "permissions": [
    "user:create",
    "member:invite",
    "member:remove",
    "role:assign",
    "group:manage"
  ]
}

This is the only response that returns the organisation id and the caller's permissions.

View in API Reference

• The caller's own profile · GET

Errors and edge cases

GET /api/users/{id} differs from other endpoints in three ways: it is not scoped to the caller's organisation, it returns 200 with an empty body for an unknown id, and it requires a Content-Type: application/json header on a GET. Use this lookup only for an explicitly authorised administrative purpose; it does not establish a tenant data boundary. Routine customer screens should use the caller profile and the organisation team list. Tenant creation is operator-only and is excluded from the customer reference.

API Reference

Open an endpoint for request fields, response examples and the interactive API console.

Related pages

• Authentication
• Policy, approvals and audit
• Roles and access
• Security and key management

Implementation resources

Team members code recipes · Users code recipes.

Use Implement a backend client for request handling, durable idempotency and outcome tracking. The developer integration coverage map links every public operation to its API Reference and contract-derived code recipe. Replace example identifiers with values from your assigned environment.