Skip to main content
Nyota Imara uses Policy-Based Access Control (PBAC) to decide what each user or organization member can do. Every protected action maps to a policy string in the format namespace:resource:action. When you make a request, the platform evaluates your current permission set against the required policy and either allows or denies the operation.

​
Policy string format

Every permission is a three-part string separated by colons: 
namespace:resource:action
PartDescriptionExamples
namespaceThe service or domain boundaryorg, identity, billing, oms
resourceThe specific entity being acted onmember, user, payment, order
actionThe operation being performedread, create, update, delete, invite, submit
A request missing the required policy receives a 403 Forbidden response with the exact policy string that was evaluated: 
{
  "success": false,
  "error": "Forbidden: You lack the required IAM policy (org:member:invite) to perform this request."
}

​
Key permissions

The table below covers the permission strings you are most likely to encounter when building on Nyota Imara.
PermissionWhat it unlocks
org:organization:readView organization details and IAM role configuration
org:organization:updateUpdate organization settings; create, edit, and delete custom roles
org:member:readList active members and pending invitations
org:member:inviteSend invitations to new team members
org:kyb:readView KYB documents and verification status
org:kyb:submitSubmit KYB documents for review
identity:user:readRead user profile and KYC status
billing:payment:createInitiate payments and add payment methods
oms:order:createCreate new orders in the commerce system
platform:org:createCreate a new organization (personal context)

​
Built-in organization roles

Every organization ships with four protected built-in roles. You cannot modify or delete them.
RoleIncluded permissions
ownerAll permissions across every namespace — equivalent to super-access within the organization.
adminorg:organization:read, org:organization:update, org:member:read, org:member:invite, org:kyb:read, org:kyb:submit
billingbilling:payment:create and all billing-namespace read and write permissions. No org management or member access.
memberorg:organization:read, org:member:read — basic read access to shared organization data.
The owner role is assigned automatically to the person who creates the organization and cannot be transferred through the API. To hand off ownership, contact Nyota Imara support.

​
Organization context and permissions

Your active permission set depends on which context you are operating in. When you send the X-Organization-Id header, Nyota Imara loads the permissions attached to your role in that specific organization. Without the header, only your personal (platform-level) permissions apply. 
# Without X-Organization-Id — personal permissions apply
GET /v1/organizations

# With X-Organization-Id — org role permissions apply
GET /v1/organizations/org_01HXYZ/members
X-Organization-Id: org_01HXYZ
This means the same user can have different effective permissions in different organizations, depending on the role they hold in each one.

​
Checking your permissions

To see the full list of roles and their mapped permissions available in your organization, call: 
GET /v1/organizations/iam/roles
Authorization: Bearer <token>
X-Organization-Id: <org-id>
The response returns each role with an isProtected flag and the list of permission IDs currently mapped to it: 
{
  "success": true,
  "data": {
    "roles": [
      {
        "id": "role_01HABC",
        "name": "admin",
        "isProtected": true,
        "permissions": ["perm_01H...", "perm_02H..."]
      },
      {
        "id": "role_01HDEF",
        "name": "auditor",
        "isProtected": false,
        "permissions": ["perm_01H..."]
      }
    ],
    "permissions": [
      { "id": "perm_01H...", "name": "org:organization:read" }
    ]
  }
}

​
Custom roles

Organization owners can create custom roles that combine any set of granular permissions. This lets you define roles like auditor (read-only access) or dispatcher (order creation only) without granting broader built-in role access.
1

List available permissions

Call GET /v1/organizations/iam/roles to get the full list of permission IDs your organization can assign.
2

Create the custom role

Post the role name and an array of permission IDs:
POST /v1/organizations/iam/roles

{
  "name": "auditor",
  "description": "Read-only access to org data and billing history",
  "permissionIds": ["perm_01H...", "perm_02H..."]
}
Role names are automatically lowercased and sanitized — only letters, digits, and underscores are kept.
3

Update or delete the role later

Update a custom role’s permissions with PATCH /v1/organizations/iam/roles/:roleId. Remove a custom role entirely with DELETE /v1/organizations/iam/roles/:roleId.
Before deleting a custom role, reassign all members currently holding that role. Deleting a role that is still assigned to users will fail with a foreign key constraint error.
Built-in roles (owner, admin, billing, member) are protected — the API blocks any attempt to modify or delete them. Custom roles are fully manageable by organization owners.