This page covers the endpoints for viewing your organization’s team and managing its role-based access control (RBAC) configuration. The built-in roles — owner, admin, billing, and member — are protected and cannot be modified or deleted. You can create custom roles (e.g., auditor, marketing) and assign specific permissions to them.
List members and pending invites Returns all active members and all outstanding invitations for the organization.
Endpoint GET https://api.nyotaimara.com/v1/organizations/:id/members
Bearer token. Format: Bearer <token>.
The ID of the organization to query. Must match the :id path parameter.
Path parameters The unique identifier of the organization.
Response Active organization members. First name of the member.
URL to the member’s avatar image. May be null.
The member’s assigned role name (e.g., "admin", "member").
ISO 8601 timestamp of when the user joined the organization.
Pending invitations that have not yet been accepted. Email address the invite was sent to.
Role that will be assigned upon acceptance.
ISO 8601 timestamp when the invite token expires.
curl --request GET \ --url https://api.nyotaimara.com/v1/organizations/org_01j9kxyz/members \ --header 'Authorization: Bearer <token>' \ --header 'X-Organization-Id: org_01j9kxyz'
{ "success" : true , "data" : { "members" : [ { "id" : "usr_abc123" , "name" : "Amina" , "email" : "amina@acmekenya.co.ke" , "avatarUrl" : "https://cdn.nyotaimara.com/avatars/amina.jpg" , "role" : "owner" , "joinedAt" : "2024-01-15T09:30:00.000Z" } ], "invites" : [ { "id" : "inv_xyz789" , "email" : "john@acmekenya.co.ke" , "role" : "admin" , "expiresAt" : "2024-02-01T09:30:00.000Z" } ] } }
Get roles and permissions Returns all roles available to the organization and the full list of permissions that can be assigned to custom roles.
Endpoint GET https://api.nyotaimara.com/v1/organizations/iam/roles
Bearer token. Format: Bearer <token>.
Active organization context.
Response All roles defined for the organization. Role name (e.g., "admin", "auditor").
true for built-in roles (owner, admin, billing, member). Protected roles cannot be modified or deleted.
Array of permission IDs assigned to this role.
All available permissions that can be assigned to custom roles.
curl --request GET \ --url https://api.nyotaimara.com/v1/organizations/iam/roles \ --header 'Authorization: Bearer <token>' \ --header 'X-Organization-Id: org_01j9kxyz'
{ "success" : true , "data" : { "roles" : [ { "id" : "role_owner" , "name" : "owner" , "isProtected" : true , "permissions" : [ "perm_org_update" , "perm_member_invite" , "perm_member_read" ] }, { "id" : "role_auditor" , "name" : "auditor" , "isProtected" : false , "permissions" : [ "perm_member_read" ] } ], "permissions" : [ { "id" : "perm_org_update" , "name" : "org:organization:update" }, { "id" : "perm_member_invite" , "name" : "org:member:invite" }, { "id" : "perm_member_read" , "name" : "org:member:read" } ] } }
Create a custom role Creates a new custom role for the organization and optionally assigns permissions to it.
Endpoint POST https://api.nyotaimara.com/v1/organizations/iam/roles
Bearer token. Format: Bearer <token>.
Active organization context.
Body Name of the new role. The value is lowercased and non-alphanumeric characters (except underscores) are replaced with underscores. Reserved names (owner, admin, billing, member) are rejected.
Human-readable description of the role’s purpose.
Array of permission IDs to assign to this role. Retrieve available IDs from GET /v1/organizations/iam/roles.
Response true on successful creation.
Confirmation message, e.g. "Organization role 'auditor' created successfully.".
curl --request POST \ --url https://api.nyotaimara.com/v1/organizations/iam/roles \ --header 'Authorization: Bearer <token>' \ --header 'X-Organization-Id: org_01j9kxyz' \ --header 'Content-Type: application/json' \ --data '{ "name": "auditor", "description": "Read-only access to financial and compliance data", "permissionIds": ["perm_member_read", "perm_kyb_read"] }'
{ "success" : true , "message" : "Organization role 'auditor' created successfully." }
Update a custom role’s permissions Replaces all permissions assigned to a custom role. The existing permission set is fully replaced — include every permission you want the role to have.
Endpoint PATCH https://api.nyotaimara.com/v1/organizations/iam/roles/:roleId
Bearer token. Format: Bearer <token>.
Active organization context.
Path parameters The ID of the role to update.
Body Complete list of permission IDs to assign to the role. The previous permissions are replaced atomically.
Response Protected roles (owner, admin, billing, member) cannot be updated. Attempting to do so returns a 403 Forbidden error.
curl --request PATCH \ --url https://api.nyotaimara.com/v1/organizations/iam/roles/role_auditor \ --header 'Authorization: Bearer <token>' \ --header 'X-Organization-Id: org_01j9kxyz' \ --header 'Content-Type: application/json' \ --data '{ "permissionIds": ["perm_member_read", "perm_kyb_read", "perm_org_read"] }'
{ "success" : true , "message" : "Role 'auditor' permissions updated." }
Delete a custom role Permanently deletes a custom role from the organization.
Endpoint DELETE https://api.nyotaimara.com/v1/organizations/iam/roles/:roleId
Bearer token. Format: Bearer <token>.
Active organization context.
Path parameters The ID of the custom role to delete.
Response true on successful deletion.
You cannot delete a role while any users are still assigned to it. Reassign those users to a different role before deleting. Protected roles (owner, admin, billing, member) can never be deleted.
curl --request DELETE \ --url https://api.nyotaimara.com/v1/organizations/iam/roles/role_auditor \ --header 'Authorization: Bearer <token>' \ --header 'X-Organization-Id: org_01j9kxyz'
{ "success" : true , "message" : "Role 'auditor' deleted successfully." }
