> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iterapay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage Team Members and Roles
> Learn how to create custom roles, add team members, assign permissions, and control access to your IteraPay merchant account.
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
See all roles currently defined on your merchant account before creating new ones.
```bash theme={null}
curl --request GET \
--url 'https://api.iterapay.com/merchants/{merchantID}/roles' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN'
```
**Expected response:**
```json theme={null}
{
"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 role by providing a name and an array of permissions to assign to it.
```bash theme={null}
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:**
```json theme={null}
{
"id": "role_b8c9d0e1-f2a3-4567-bcde-678901234567",
"name": "Support",
"permissions": ["invoices.read", "transactions.read"]
}
```
To change a role's name or permissions, send a `PUT` request with the updated values.
```bash theme={null}
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.
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.
```bash theme={null}
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
Retrieve a paginated list of all members on your account. You can filter by role to quickly see who holds a specific role.
```bash theme={null}
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:**
```json theme={null}
{
"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.
To update the role assigned to an existing member, send a `PUT` request with their `userID` and the new `roleID`.
```bash theme={null}
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 to revoke their access to your merchant account. This does not delete their IteraPay user account — it only removes them from your merchant.
```bash theme={null}
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:
```bash theme={null}
curl --request GET \
--url 'https://api.iterapay.com/merchants/{merchantID}/permissions' \
--header 'Authorization: Bearer YOUR_JWT_TOKEN'
```
**Expected response:**
```json theme={null}
{
"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
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.
Remove members who no longer work with your team promptly. Dormant accounts with active permissions are a security risk.
Name roles after job functions (e.g., "Finance", "Developer", "Support") rather than individual people. Roles should be reusable as your team grows.