User Roles & Permissions

User Types and Access

Payrails portal supports two types of users: Single Sign-On (SSO) users and Non-SSO users. Each user type has distinct characteristics regarding access and permissions within the portal.

Single Sign-On (SSO) Users

SSO users access the portal through a centralized authentication system. Upon joining the portal, SSO users are assigned the default user role called "Spectator." This role is designed for limited access, allowing users to view only the Dashboard section within the merchant portal. Users requiring additional access must contact their administrator to obtain relevant permissions for the portal.

Activating SSO Access for Merchants

By default, SSO access is not activated for merchants within the Payrails portal. Merchants interested in using SSO functionality must contact their Payrails business partner. At the moment merchants portal supports OKTA as an SSO provider.

Non-Single Sign-On (Non-SSO) Users

Non-SSO users access the portal through traditional authentication methods. Unlike SSO users, they do not receive automatic role assignments upon joining the portal. Instead, administrators manually assign roles and permissions based on the user's responsibilities and access requirements.

Introduction to Roles and Permissions

Welcome to the comprehensive documentation on user roles and permissions for Payrails. This section offers a detailed overview emphasizing the critical role of managing roles and permissions within the system.

RBAC Explained

Payrails adopts the Role-Based Access Control (RBAC) model to efficiently manage user permissions.

Role-Based Access Control (RBAC) is a robust security model that organizes access permissions based on user roles. In RBAC, users are assigned specific roles, each with well-defined permissions. Rather than assigning permissions directly to individual users, access is governed through roles. This streamlined approach simplifies administration, enhances overall security, and ensures that users only possess the access necessary for their designated roles. This minimizes the risk of unauthorized actions, contributing to improved system management.

There are two primary methods through which users interact with the Payrails system. Users can utilize the merchant portal for tasks such as configuring workflows or gaining insights into executions and reports. Alternatively, they can interact programmatically via API and SDK. In both scenarios, user roles are assigned to the individuals managing user accounts or to the machines involved in machine-to-machine communication.

User Roles Explained

Dive into the diverse user roles within Payrails. This section provides a comprehensive overview of the distinctive characteristics and responsibilities associated with each role:


User that has the permissions for all view and write actions that are available for the merchants. This role is usually assigned to technical or business leadership which requires them to take certain actions such as obtaining API keys or setting up business rules, and view certain information to perform their jobs. Admin has full access to all of the portal features.


The user has view and write permissions for certain actions. This role is usually assigned to merchant employees working in customer support teams, and back office operation teams which require them to take certain actions such as refund, disabling an instrument, and viewing certain information to perform their jobs. Operators can search, view, capture, cancel, and refund payments. Additionally, they can view and investigate executions, and cancel and capture them.


The user has only view permissions for portal actions. This role is usually assigned to employees who need to view certain information to perform their jobs (f.e. check the status of the latest payments). Viewers can search and view payments and executions.

Spectator (SSO Only Role)

Users with restricted access to the portal dashboard are automatically assigned this role upon joining via SSO. Their next step is to request their administrators to assign them appropriate roles such as admin, operator, or viewer.

Roles & Permissions Matrix

Visualize the roles and their corresponding permissions across various services with our comprehensive matrix. This tool illustrates the access levels of each role to specific actions within key service categories, including Auth, Ledger, Merchant, and Payment.

Below, we present individual Role & Permissions Matrices for each service:

System Configuration

List all clients.
List API secret.
List MTLS certificate.
Read an MTLS certificate.
Read details of a specific client.
Create a new transfer.
Rotate the secret key for a client.
Create a new client.
Delete a client.
Create a new key.
Create an MTLS certificate
Revoke an MTLS certificate

User Management

List all users.
Read details of a specific user.
List all available roles.
Read details of a specific role.
Create a new user.
Assign a role to a user.
Block a user's access.
Unblock a user.


View notification config details
List notification configs
Create a notification config.
Update notification config.
Delete notification config.


List all executions.
Read details of a specific execution.
Lookup execution details.
Authorize an execution.
Cancel an execution.
Capture an execution.
Confirm an execution.
Create a new execution.
Refund an execution.

Workspace Management

List all workspaces.
Create a new workspace.
Update workspace.

Merchant Configuration

Read consumer checkout configuration.
List all holders.
Read details of a specific holder.
List all rulesets.
Read details of a specific ruleset.
List all workflows.
Read details of a specific workflow.
Read SDK configuration.
Read details of fields.
List all fields.
Write consumer checkout configuration.
Create a new holder.
Lock a holder.
Unlock a holder.
Create a new ruleset.
Create a new workflow.

Payments & Instruments

List all providers.
Read details of a specific provider.
List provider configurations.
Read details of a specific provider config.
List all payments.
Read details of a specific payment.
List payment statistics.
Read details of a specific instrument.
List all instruments.
List all integrations.
Read details of a specific token.
List all tokens.
List raw notifications.
Read vault configuration.
List API logs.
Read details of a specific API log.
Read BIN information.
Read analytics data.
Proxy actions for providers.
Create a new provider configuration.
Delete a provider configuration.
Update an existing provider configuration.
Update an existing instrument.
Delete an instrument.


Get dataset details
List datasets
Get export details
List exports
Create an export

How to Assign Roles & Permissions

Discover step-by-step instructions on how administrators can proficiently assign roles and permissions within the Payrails system. This section offers insightful guidance for effective user access management.


To manage other users' roles, you must have the ADMIN role assigned to your account.

Step 1: Log into the Merchants Portal

Begin by logging into the Merchants Portal using your credentials.

Step 2: Navigate to the /users Page

Once logged in, navigate to the "/users" page. This page provides an overview of all registered users within the system.

Step 3: Select User and Assign a New Role

  • Identify the user for whom you want to assign a new role.
  • Select the user's profile to access their details.
  • Locate the option to assign roles.
  • Choose the desired role from the available options.
  • Save or confirm your selection to apply the new role to the user.

Optional Step: Block a User

If needed, you can also block a user to restrict their access to the portal. A blocked user won't be able to access the portal until you unblock them.

Best Practices

  • Least Privilege Principle: Assign the minimum necessary permissions to users based on their roles. This reduces the risk of unauthorized access and potential security breaches.
  • Regular Audits: Periodically review and update user roles and permissions to align with organizational changes. Remove unnecessary access for users who have changed roles or responsibilities.
  • Training: Provide training sessions for users on the assigned roles and the associated permissions. This ensures that everyone is aware of the actions they can perform within the system.


How can I request additional permissions for my role?

To request additional permissions, reach out to your administrator or the designated role manager. They can assess your request, considering the principle of least privilege, and make necessary adjustments if required.

Can I have multiple roles assigned to my account?

No, each account is assigned a single role to maintain clarity and adhere to the principle of least privilege. If your responsibilities change, contact the administrator to reassess and adjust your role accordingly.

What should I do if I suspect unauthorized access?

If you suspect unauthorized access or notice any unusual activity, immediately report it to your administrator. They will investigate the issue and take appropriate measures to secure the system.

Are role changes effective immediately?

Yes, role changes take effect immediately upon assignment. However, it's recommended to log out and log back in to ensure the updated roles and permissions are applied consistently.

How often should roles and permissions be audited?

Roles and permissions should be audited regularly, at least quarterly, or whenever there are organizational changes. Regular audits help ensure that access levels align with current business requirements and reduce security risks.

Can I customize roles based on specific business needs?

No, the roles are predefined to maintain consistency and security. If you have specific access requirements, discuss them with your administrator, and they can assess whether adjustments are necessary within the existing role structure.

Why am I getting 405 Not Allowed when accessing the portal via SSO (e.g. Okta)?

There is a known limitation with our portal which prevents direct connection from your SSO portal (e.g. Okta) to our portal. To access the portal with you SSO login, you need to access via the direct portal URL instead (e.g. https ://