Skip to main content
Nyota Imara lets you build a team around your organization with role-based access control. You can invite teammates by email, assign them a built-in role, and create custom roles with the exact permissions your workflows require.

​
Built-in roles

Every organization comes with four built-in roles:
RoleTypical use
ownerFull control — billing, team, settings, and all features
adminManage team and settings, but not billing
billingManage payments and subscriptions only
memberOperational access to commerce, logistics, and notifications

​
Invite a team member

Send a POST request to /v1/organizations/:id/invites. The invitee receives an email with a secure, 7-day link to join. 
curl -X POST https://api.nyotaimara.com/v1/organizations/org_01j9kxp8a3bvc0nqrtzwmde4fy/invites \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "amara.odhiambo@savanasupplies.co.ke",
    "roleName": "admin"
  }'
Response: 
{
  "success": true,
  "message": "Invitation sent to amara.odhiambo@savanasupplies.co.ke."
}
If the email address already belongs to a member of the organization, the server returns 409 Conflict. Re-sending to a pending invitee replaces the previous invite.

​
Accept an invitation

The invitee clicks the link in their email and signs in at https://accounts.nyotaimara.com/invites/accept. Once authenticated, the invitation is accepted by calling: 
curl -X POST https://api.nyotaimara.com/v1/organizations/invites/accept \
  -H "Authorization: Bearer <invitee_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a3f8e2c1d9b047fe..."
  }'
Response: 
{
  "success": true,
  "message": "Successfully joined the organization!"
}
The accept endpoint is a personal context route — it does not require the X-Organization-Id header. The invite token carries the organization and role information.

​
List members and pending invites

Retrieve all active members and unaccepted invitations in one call: 
curl https://api.nyotaimara.com/v1/organizations/org_01j9kxp8a3bvc0nqrtzwmde4fy/members \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy"
Response: 
{
  "success": true,
  "data": {
    "members": [
      {
        "id": "usr_01jb2kqp8a3bvc0nqrtzwmde9xy",
        "name": "Amara",
        "email": "amara.odhiambo@savanasupplies.co.ke",
        "avatarUrl": "https://cdn.nyotaimara.com/avatars/amara.jpg",
        "role": "admin",
        "joinedAt": "2025-11-05T07:14:00.000Z"
      }
    ],
    "invites": [
      {
        "id": "inv_01jb3nrm4p7xyz",
        "email": "brian.kamau@savanasupplies.co.ke",
        "role": "member",
        "expiresAt": "2025-11-12T07:14:00.000Z"
      }
    ]
  }
}

​
Custom roles

If the four built-in roles do not match your access requirements, create a custom role with a specific set of permission IDs.

​
Create a custom role

curl -X POST https://api.nyotaimara.com/v1/organizations/iam/roles \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Logistics Manager",
    "description": "Can create delivery estimates and view orders, but cannot access billing.",
    "permissionIds": [
      "perm_logistics_delivery_read",
      "perm_oms_order_read"
    ]
  }'

​
Update a custom role’s permissions

curl -X PATCH https://api.nyotaimara.com/v1/organizations/iam/roles/role_01jb9xyz \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy" \
  -H "Content-Type: application/json" \
  -d '{
    "permissionIds": [
      "perm_logistics_delivery_read",
      "perm_oms_order_read",
      "perm_oms_order_create"
    ]
  }'

​
Delete a custom role

curl -X DELETE https://api.nyotaimara.com/v1/organizations/iam/roles/role_01jb9xyz \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy"
Deleting a role does not automatically remove it from members who hold it. Reassign affected members before deleting a role to avoid access inconsistencies.

​
View available roles and permissions

To see all current roles and the full list of available permission IDs for your organization: 
curl https://api.nyotaimara.com/v1/organizations/iam/roles \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy"

​
Endpoint reference

MethodEndpointRequired policy
POST/v1/organizations/:id/invitesorg:member:invite
POST/v1/organizations/invites/acceptAuthenticated (no org context)
GET/v1/organizations/:id/membersorg:member:read
GET/v1/organizations/iam/rolesorg:organization:read
POST/v1/organizations/iam/rolesorg:organization:update
PATCH/v1/organizations/iam/roles/:roleIdorg:organization:update
DELETE/v1/organizations/iam/roles/:roleIdorg:organization:update