Roles and access

Who this is for

Bank administrators, operations managers and security reviewers who decide who may use Quant Flow and what they may do. Platform access covers named users, connected systems and approval responsibilities. Infrastructure access is a separate responsibility in a client-hosted deployment.

Give people the permissions their duties require, keep submission and approval responsibilities separate and review access when someone changes role or leaves. The implementation details below show how administrators configure those controls.

Separate the caller, approver and signing authority

Your backend's principal needs permissions to submit the intended operations. A person needs the appropriate user identity and task assignment to approve them. The custody-controlled signing address needs the relevant contract authority. Granting one of these does not grant the others.

Use a role to decide which API actions a person may perform. Use an approval group to select eligible decision-makers for a task. A group is not an API role and does not itself grant payment-submission permissions. Keep these assignments distinct when building administration screens and reviewing access.

Read the returned permission catalogue and assigned roles before provisioning access. Do not assume a role label means all operations are available, or that an organisation administrator can perform Quant's platform provisioning. For a backend, arrange machine-client onboarding and secret handling through Authentication; the one-time secret endpoint is not a self-service client-creation API.

Access to the platform

Platform roles and custom roles

Each user holds one role. A role grants a set of permissions.

GET /api/tenants/{id}/roles returns every role your organisation may assign, each with the flat set of permissions it grants. Use it to read exactly what each platform role grants. The custom flag separates platform roles from your own. The path organisation must equal the caller's tenant_id claim; a mismatch is a 403. No permission is needed to list roles.

The permission catalogue

GET /api/permissions returns every permission a custom role can be built from, in resource:action form, for example policy:read or group:manage. The catalogue is platform reference data, the same for every organisation. No permission is needed to read it.

Building a custom role

POST /api/tenants/{id}/roles creates a role owned by your organisation. It requires role:create.

• You cannot grant what you do not hold. A caller may grant only permissions they hold themselves.
• Names are unique. A platform role name, or a name your organisation already uses, is a 409. The comparison ignores case.
• The response is 200, not 201.

PUT /api/tenants/{id}/roles/{roleId}/permissions replaces a role's permissions and requires role:update. It is a full replacement: a permission left out is revoked.

Team members

• POST /api/tenants/{id}/users invites a user. The permission required depends on the role granted: super_admin:create, admin:create or user:create. The user starts INVITED and cannot sign in until they set a password with POST /api/auth/activate or POST /api/auth/new-password.
• PATCH /api/tenants/{id}/users/{userId}/role changes a member's role and requires role:assign. A caller cannot change their own role or the organisation owner's.
• DELETE /api/tenants/{id}/users/{userId} removes a member. Removal is a soft delete: access ends and the record is kept.

Approval groups

POST /api/tenants/{id}/groups creates a named group of approvers that policies reference by key. The key is immutable and matches ^#[a-z][a-z0-9_]{0,62}$, for example #mlro. Creating and managing groups requires group:manage. Members are added with POST /api/tenants/{id}/groups/{groupId}/members. See Policy, approvals and audit.

Machine clients

Bank systems call the API as machine clients, not as users. Give each integrating system its own client so its activity is attributable and it can be revoked on its own. See Identities and entitlements.

Use the permission catalogue and the access checks documented on each endpoint. Verify deployed enforcement with the operator where the reference marks checks as planned.
Quant creates the organisation and first administrator during onboarding; the administrator completes the invitation and initial password flow.

Permissions and approval groups are different

%%{init: {"theme": "neutral"}}%%
flowchart TB
    Catalog["Permission catalogue"] --> Role["Role / granted permissions"]
    Role --> User["Named team member"]
    User --> Calls["Permitted API actions"]
    User --> Group["Approval-group membership"]
    Group --> Policy["Policy references group key"]
    Policy --> Tasks["Resolved approvers / approval tasks"]

A role controls API permissions; a group identifies approvers for policy tasks. Group membership is not a substitute for endpoint permissions or custody signing authority.

Permission catalogue · Roles · Approval groups · Approval tasks

Access to the infrastructure (client-hosted deployments)

The platform has no privileged administration API. In a client-hosted deployment, the bank administers the infrastructure with its own tooling, under its own privileged-access management and joiner, mover and leaver procedures. Quant provides the tier definitions below, the cluster role mapping and the runbooks. The bank assigns its own people to the tiers.

Privileged access is never standing. An administrative action needs:

• Phishing-resistant multi-factor authentication, with conditional access on device, location and risk.
• A just-in-time elevation request with a justification and a time limit. The grant expires automatically.
• Approval by a second person.
• Separate people for platform administration and key administration.
• A recorded session, and an audit record in the bank's security monitoring.

Quant engineers hold no standing access to a client-hosted production environment. Where the bank grants support access, it follows the same just-in-time path under the bank's approval.

Agree infrastructure-administration ownership, privileged-access review and evidence provision in the Quant-hosted operating model. These controls are separate from the user roles exposed by the API.

Worked example

List the roles your organisation can assign, with the permissions each grants.

GET /api/tenants/f312a03a-d897-4d07-ab17-4a0b69e9b547/roles HTTP/1.1
Host: api.qfp.quantnetwork.net
Authorization: Bearer <access token>
API-Version: 1.0.0

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

{
  "pageNumber": 0,
  "pageSize": 20,
  "totalResults": 4,
  "items": [
    {
      "id": "5c2f1e8a-91b4-4d33-8a77-0e1b6c9d2f41",
      "role": "ADMIN",
      "description": "Manages the tenant",
      "custom": false,
      "permissions": [
        "admin:create",
        "user:create",
        "member:invite",
        "member:remove",
        "automation:create"
      ]
    },
    {
      "id": "9a7d3b61-2c48-4f90-b5e2-77c1a0d4e6f3",
      "role": "Analyst",
      "description": "Reads policies",
      "custom": true,
      "permissions": [
        "policy:read"
      ]
    }
  ]
}

Create a custom role that can only read policies:

POST /api/tenants/f312a03a-d897-4d07-ab17-4a0b69e9b547/roles HTTP/1.1
Host: api.qfp.quantnetwork.net
Authorization: Bearer <access token>
API-Version: 1.0.0
Content-Type: application/json

{
  "name": "Analyst",
  "description": "Reads policies",
  "permissions": [
    "policy:read"
  ]
}

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

{
  "id": "9a7d3b61-2c48-4f90-b5e2-77c1a0d4e6f3",
  "role": "Analyst",
  "description": "Reads policies",
  "custom": true,
  "permissions": [
    "policy:read"
  ]
}

View in API Reference

• List roles · GET
• Create a custom role · POST

Errors and edge cases

API Reference

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

Related pages

• Identities and entitlements
• Authentication
• Policy, approvals and audit
• Security and key management
• Audit and evidence

Implementation resources

Roles code recipes · Permissions 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.