Manage Team Members and Roles

IteraPay’s team management system lets you grant colleagues access to your merchant account with precisely the permissions they need. You define roles that group a set of permissions, then assign those roles to members. A finance manager, for example, might have access to withdrawals and collection, while a developer only needs access to invoice creation and webhooks. This guide covers how to set up roles, add members, and manage access over time.

How roles and permissions work

Every member of your merchant account is assigned a role. A role is a named collection of permissions — granular access controls that determine which API actions and dashboard features a member can use.

Permissions are defined and enforced server-side. Even if a member knows an API endpoint, they cannot use it without the corresponding permission in their role.

Concept	Description
Role	A named template that groups one or more permissions (e.g., “Finance”, “Developer”)
Permission	A specific capability, such as creating invoices or initiating withdrawals
Member	A user added to the merchant account with an assigned role

Manage roles

List existing roles

See all roles currently defined on your merchant account before creating new ones.

curl --request GET \
  --url 'https://api.iterapay.com/merchants/{merchantID}/roles' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'

Expected response:

{
  "roles": [
    {
      "id": "role_f6a7b8c9-d0e1-2345-fabc-456789012345",
      "name": "Finance",
      "permissions": ["withdrawals.create", "collection.init", "funds.read"]
    },
    {
      "id": "role_a7b8c9d0-e1f2-3456-abcd-567890123456",
      "name": "Developer",
      "permissions": ["invoices.create", "invoices.read", "webhooks.manage"]
    }
  ]
}

Create a new role

Create a role by providing a name and an array of permissions to assign to it.

curl --request POST \
  --url 'https://api.iterapay.com/merchants/{merchantID}/roles' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Support",
    "permissions": ["invoices.read", "transactions.read"]
  }'

Expected response:

{
  "id": "role_b8c9d0e1-f2a3-4567-bcde-678901234567",
  "name": "Support",
  "permissions": ["invoices.read", "transactions.read"]
}

Update an existing role

To change a role’s name or permissions, send a PUT request with the updated values.

curl --request PUT \
  --url 'https://api.iterapay.com/merchants/{merchantID}/roles' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "role_b8c9d0e1-f2a3-4567-bcde-678901234567",
    "name": "Support",
    "permissions": ["invoices.read", "transactions.read", "members.read"]
  }'

Updating a role immediately affects all members currently assigned to it. Review who holds the role before making changes.

Delete a role

Remove a role when it’s no longer needed. You cannot delete a role that still has members assigned to it — reassign or remove those members first.

curl --request DELETE \
  --url 'https://api.iterapay.com/merchants/{merchantID}/roles' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "role_b8c9d0e1-f2a3-4567-bcde-678901234567"
  }'

Manage members

List current members

Retrieve a paginated list of all members on your account. You can filter by role to quickly see who holds a specific role.

curl --request GET \
  --url 'https://api.iterapay.com/merchants/{merchantID}/members?role=role_f6a7b8c9-d0e1-2345-fabc-456789012345' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'

Expected response:

{
  "members": [
    {
      "userID": "usr_c9d0e1f2-a3b4-5678-cdef-789012345678",
      "email": "alice@yourcompany.com",
      "roleID": "role_f6a7b8c9-d0e1-2345-fabc-456789012345",
      "roleName": "Finance",
      "joinedAt": "2024-01-01T09:00:00Z"
    }
  ],
  "total": 1,
  "page": 1
}

Omit the role query parameter to return all members regardless of role.

Change a member's role

To update the role assigned to an existing member, send a PUT request with their userID and the new roleID.

curl --request PUT \
  --url 'https://api.iterapay.com/merchants/{merchantID}/members' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "userID": "usr_c9d0e1f2-a3b4-5678-cdef-789012345678",
    "roleID": "role_a7b8c9d0-e1f2-3456-abcd-567890123456"
  }'

The change takes effect immediately.

Remove a member

Remove a member to revoke their access to your merchant account. This does not delete their IteraPay user account — it only removes them from your merchant.

curl --request DELETE \
  --url 'https://api.iterapay.com/merchants/{merchantID}/members' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "userID": "usr_c9d0e1f2-a3b4-5678-cdef-789012345678"
  }'

Check your own permissions

If you’re not sure what you’re allowed to do on a merchant account, retrieve your own permission set:

curl --request GET \
  --url 'https://api.iterapay.com/merchants/{merchantID}/permissions' \
  --header 'Authorization: Bearer YOUR_JWT_TOKEN'

Expected response:

{
  "roleID": "role_f6a7b8c9-d0e1-2345-fabc-456789012345",
  "roleName": "Finance",
  "permissions": [
    "withdrawals.create",
    "collection.init",
    "funds.read"
  ]
}

If you receive a 403 Forbidden response on any endpoint, check your permissions here to confirm whether your role includes the required access.

Best practices

Follow the principle of least privilege

Assign each member only the permissions they need for their specific job function. Avoid creating a single “admin” role for all team members unless they genuinely need full access.

Audit your members list regularly

Remove members who no longer work with your team promptly. Dormant accounts with active permissions are a security risk.

Use descriptive role names

Name roles after job functions (e.g., “Finance”, “Developer”, “Support”) rather than individual people. Roles should be reusable as your team grows.

Get Started

Core Concepts

Guides

Manage Team Members and Roles

How roles and permissions work

Manage roles

Manage members

Check your own permissions

Best practices

​How roles and permissions work

​Manage roles

​Manage members

​Check your own permissions

​Best practices

How roles and permissions work

Manage roles

Manage members

Check your own permissions

Best practices