Roles

Base path: https://gateway.useyona.com/a/v1/organizations/:orgId/roles

Roles define sets of permissions that can be assigned to users and API keys within an organization. Yona ships with system roles (e.g. Owner, Admin, Member) that cannot be modified, and supports custom roles for fine-grained access control.

List roles

GET /a/v1/organizations/:orgId/roles

Returns all roles in the organization, including system and custom roles.

bash

curl https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/roles \
  -H "Authorization: Bearer sk_test_your_key_here"

Create role

POST /a/v1/organizations/:orgId/roles

Create a custom role with a specific set of permissions.

Request body

Field	Type	Required	Description
`name`	string	Yes	Unique identifier for the role (lowercase, hyphens allowed)
`displayName`	string	Yes	Human-readable name
`description`	string	No	What this role is for
`permissions`	string[]	Yes	List of permission strings to grant

bash

curl -X POST https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/roles \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "invoice-clerk",
    "displayName": "Invoice Clerk",
    "description": "Can create and view invoices only",
    "permissions": ["invoices:create", "invoices:read"]
  }'

Error responses

Status	Description
`400`	Invalid permissions or missing required fields
`409`	A role with that name already exists in the organization

Get role

GET /a/v1/organizations/:orgId/roles/:roleId

Retrieve a single role with details about how many users and API keys it is assigned to.

bash

curl https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/roles/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer sk_test_your_key_here"

Update role

PATCH /a/v1/organizations/:orgId/roles/:roleId

Update a custom role’s name, display name, description, or permissions. System roles cannot be updated.

Request body

Field	Type	Required	Description
`name`	string	No	Updated identifier
`displayName`	string	No	Updated display name
`description`	string	No	Updated description
`permissions`	string[]	No	Replaces the entire permission set

bash

curl -X PATCH https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/roles/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Invoice Manager",
    "description": "Can create, view, and submit invoices",
    "permissions": ["invoices:create", "invoices:read", "invoices:submit"]
  }'

Error responses

Status	Description
`400`	Invalid permissions
`403`	Cannot update system or immutable roles
`404`	Role not found

Delete role

DELETE /a/v1/organizations/:orgId/roles/:roleId

Delete a custom role. System roles and immutable roles cannot be deleted. Users and API keys currently assigned this role will need to be reassigned.

bash

curl -X DELETE https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/roles/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "Authorization: Bearer sk_test_your_key_here"

Error responses

Status	Description
`403`	Cannot delete system or immutable roles
`404`	Role not found

Get available permissions

GET /a/v1/organizations/:orgId/roles/permissions/available

Returns all permissions that can be assigned to roles, grouped by category. Use this to build a role creation UI or to validate permission strings before creating or updating a role.

bash

curl https://gateway.useyona.com/a/v1/organizations/9f8e7d6c-5b4a-3210-fedc-ba9876543210/roles/permissions/available \
  -H "Authorization: Bearer sk_test_your_key_here"

The collection.read and collection.manage permissions gate the Collection API. Grant them to an API key or custom role to let it mint virtual accounts and reconcile buyer payments.