Role-Based Permissions

This guide shows you how to manage user permissions in your organization using Amigo's role management APIs.

What You'll Learn

How to create and manage roles for different user types
How to control what actions users can perform
How to assign roles to users
Common permission patterns and best practices

Getting Started

Every user in your organization must have exactly one role. Roles define what actions users can perform, such as creating conversations, viewing data, or managing other users.

Basic Concepts

Role: A set of permissions you assign to users (e.g., "Admin", "Moderator", "Viewer")
Permission: A specific action like "create conversation" or "view user data"
Conditions: Rules that limit when permissions apply (e.g., "only in your organization")

Working with Role APIs

Get roles

get

/v1/{organization}/role/

Return a list of roles in this organization.

Permissions

This endpoint may be impacted by the following permissions:

Only roles that the authenticated user has the Role:GetRole permission on will be returned.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization.

Path parameters

organizationstringRequired

Query parameters

return_permission_grantsbooleanOptional

Whether to return permission grants.

Default: false

idstring[]Optional

The IDs of the roles to retrieve.

Default: []

namestring[]Optional

The names of the roles to retrieve.

Default: []

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Responses

200

Succeeded

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization is not found.

422

Invalid request path parameter or request query parameter failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

get

/v1/{organization}/role/

GET /v1/{organization}/role/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*

{
  "roles": [
    {
      "id": "text",
      "name": "text",
      "description": "text",
      "frontend_view": "client",
      "permission_grants": [
        {
          "permission_name": "text",
          "conditions": {
            "ANY_ADDITIONAL_PROPERTY": {
              "type": "Equals",
              "value": null
            }
          }
        }
      ]
    }
  ]
}

Create a role

post

/v1/{organization}/role/

Create a new role.

Permissions

This endpoint requires the following permissions:

Role:CreateRole for the role.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

role_namestring · min: 1 · max: 256Required

The name of the role to create. The role must have a max length of 256 characters.

descriptionstring · min: 1Required

A description about the role.

frontend_viewstring · enumRequired

The frontend view for users of this role.

Possible values:

Responses

201

Succeeded

application/json

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization or inherited role is not found.

409

Role with the same name already exists in this organization.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 20 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/role/

POST /v1/{organization}/role/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 187

{
  "role_name": "text",
  "description": "text",
  "permission_grants": [
    {
      "permission_name": "text",
      "conditions": {
        "ANY_ADDITIONAL_PROPERTY": {
          "type": "Equals",
          "value": null
        }
      }
    }
  ],
  "frontend_view": "client"
}

{
  "role_id": "text"
}

Modify a role

post

/v1/{organization}/role/{role_name}

Modify an existing role. The roles are modified in-place unless immutable fields are modified, in which case a new role with the same name is created, and all users/API keys assigned to the previous role are switched to the new role. The old role document will expire after 1 day.

Permissions

This endpoint requires the following permissions:

Role:ModifyRole for the role.

This endpoint may require the authenticated user to have great privileges than the new role if a new role document is created as a result of immutable field changes.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

role_namestringRequired

The name of the role.

organizationstringRequired

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

descriptionany ofOptional

A description about the role. Only updated if specified. This field is a mutable field.

string · min: 1Optional

nullOptional

permission_grantsany ofOptional

A list of permission grants associated with this role. Only updated if specified. This field is an immutable field.

nullOptional

frontend_viewany ofOptional

The frontend view for the user of this role. Only updated if specified. This field is an immutable field.

string · enumOptionalPossible values:

nullOptional

Responses

200

Succeeded

application/json

role_idstringRequired

The identifier of the updated role.

400

Base roles cannot inherit from other roles.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization, role, or inherited role is not found.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 10 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/role/{role_name}

POST /v1/{organization}/role/{role_name} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 168

{
  "description": "text",
  "permission_grants": [
    {
      "permission_name": "text",
      "conditions": {
        "ANY_ADDITIONAL_PROPERTY": {
          "type": "Equals",
          "value": null
        }
      }
    }
  ],
  "frontend_view": "client"
}

{
  "role_id": "text"
}

Assign a role to user

post

/v1/{organization}/role/{role_name}/assign

Assign a role to a user.

Permissions

This endpoint requires the following permissions:

The authenticated user to have greater privileges than the role being assigned.

Authorizations

AuthorizationstringRequired

The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.

AuthorizationstringRequired

Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.

X-ORG-IDstringRequired

Path parameters

organizationstringRequired

role_namestringRequired

The name of the role to assign.

Header parameters

x-mongo-cluster-nameany ofOptional

The Mongo cluster name to perform this request in. This is usually not needed unless the organization does not exist yet in the Amigo organization infra config database.

stringOptional

nullOptional

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

user_idstringRequired

The identifier of the user to assign the role to.

Responses

200

Succeeded

application/json

role_idstringRequired

The identifier of the role assigned to the user.

401

Invalid authorization credentials.

403

Missing required permissions.

404

Specified organization, role, or user is not found.

422

Invalid request path parameter or request body failed validation.

429

The user has exceeded the rate limit of 1000 requests per minute for this endpoint.

503

The service is going through temporary maintenance.

post

/v1/{organization}/role/{role_name}/assign

POST /v1/{organization}/role/{role_name}/assign HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "user_id": "text"
}

{
  "role_id": "text"
}

Creating Permission Rules

When creating roles, you define permission grants that specify what users can do. Each grant has three parts:

{
    "action": "Allow",
    "permission_name": "Conversation:CreateConversation", 
    "conditions": {
        "org_id": {
            "type": "Equals",
            "value": "{self_org_id}"
        }
    },
    "description": "Allow creating conversations in user's organization"
}

Permission Names

Permissions use a simple Category:Action format:

Conversation:CreateConversation - Create new conversations
Conversation:GetConversation - View existing conversations
User:GetUserInfo - View user information

Adding Conditions

Conditions let you limit when permissions apply. For example, you might want users to only access data in their own organization:

{
    "conditions": {
        "org_id": {
            "type": "Equals", 
            "value": "{self_org_id}"
        }
    }
}

The {self_org_id} automatically becomes the user's organization when the permission is checked.

Condition Types

You can use these condition types to control when permissions apply:

Type

When to Use

Example

Equals

Grant permission for a specific value

{"type": "Equals", "value": "premium_service"}

NotEquals

Block permission for a specific value

{"type": "NotEquals", "value": "restricted_service"}

In

Allow permission for any of several values

{"type": "In", "values": ["basic", "premium", "enterprise"]}

Variable Substitution

{self_org_id}: the authenticated user’s organization ID
{self}: the authenticated user’s user ID (useful for user- or conversation-owner checks)
{self_role_name}: the authenticated user’s role name (used by some role-related permissions)

Understanding Permission Behavior

How Permissions Are Checked

When a user tries to perform an action, the system:

Looks at all permission grants in the user's role
Finds grants that match the action being attempted
Checks if any conditions are met
Deny grants always win - if any deny grant matches, the action is blocked
If no deny grants match but an allow grant does, the action is permitted

Key Rule: Deny permissions always take precedence over allow permissions.

What Happens When Permissions Are Missing

Different API endpoints handle missing permissions in different ways:

Some endpoints return errors:

{
    "error": "Forbidden", 
    "message": "Missing required permission: Conversation:CreateConversation"
}

Others filter results silently:

GetConversations only returns conversations you can access
GetUsers only shows users you have permission to view

Some hide specific fields:

If you don't have message-level access, final_message may be empty in GetConversations
If you lack service-version access, version_set_info may be omitted in GetConversations
This prevents errors while protecting sensitive information

Role Hierarchy Requirements

When managing other users' roles, you need sufficient privileges:

Inviting users: You can only assign roles with equal or fewer privileges than your own
Creating API keys: API keys can only have roles with equal or fewer privileges than yours
Modifying roles: You can only create/edit roles that have equal or fewer privileges than yours

Common Role Examples

Content Moderator

A role that can review admin-visible conversations/messages but cannot interact in them:

{
  "role_name": "content_moderator",
  "description": "Can review admin-visible conversations in their organization",
  "is_base_role": false,
  "frontend_view": "admin",
  "permission_grants": [
    {
      "action": "Allow",
      "permission_name": "Conversation:GetConversation",
      "conditions": {
        "org_id": {"type": "Equals", "value": "{self_org_id}"},
        "conversation_visible_to_admin": {"type": "Equals", "value": true}
      },
      "description": "View admin-visible conversations in own organization"
    },
    {
      "action": "Allow",
      "permission_name": "Conversation:GetMessage",
      "conditions": {
        "org_id": {"type": "Equals", "value": "{self_org_id}"},
        "conversation_visible_to_admin": {"type": "Equals", "value": true}
      },
      "description": "Read messages in admin-visible conversations"
    },
    {
      "action": "Deny",
      "permission_name": "Conversation:InteractWithConversation",
      "conditions": {},
      "description": "Cannot interact in conversations"
    }
  ]
}

Read-Only User

A role that can only view their own conversations, never create or interact:

{
  "role_name": "viewer",
  "description": "Can only view own conversations",
  "is_base_role": false,
  "frontend_view": "client",
  "permission_grants": [
    {
      "action": "Allow",
      "permission_name": "Conversation:GetConversation",
      "conditions": {
        "org_id": {"type": "Equals", "value": "{self_org_id}"},
        "conversation_user_id": {"type": "Equals", "value": "{self}"}
      },
      "description": "View only the authenticated user's conversations"
    },
    {
      "action": "Deny",
      "permission_name": "Conversation:CreateConversation",
      "conditions": {},
      "description": "Cannot create new conversations"
    },
    {
      "action": "Deny",
      "permission_name": "Conversation:InteractWithConversation",
      "conditions": {},
      "description": "Cannot interact in conversations"
    }
  ]
}

Best Practices

Start Simple

Begin with basic roles like "Admin", "User", and "Viewer" before creating complex permission structures.

Use Organization Scoping

Almost all permissions should include "org_id": {"type": "Equals", "value": "{self_org_id}"} to keep users within their organization.

Prefer Allow Over Deny

Design roles with specific allow permissions rather than broad permissions with deny exceptions.

Test Permission Changes

Always test role modifications in a development environment before applying them to production users.

Document Your Roles

Use clear role names and descriptions so other developers understand their purpose.

PreviousPermissions NextTemporary Permission Grants

Last updated 5 months ago

Was this helpful?

Good afternoon

hashtagWhat You'll Learn

hashtagGetting Started

hashtagBasic Concepts

hashtagWorking with Role APIs

hashtagGet roles

Permissions

hashtagCreate a role

Permissions

hashtagModify a role

Permissions

hashtagAssign a role to user

Permissions

hashtagCreating Permission Rules

hashtagPermission Names

hashtagAdding Conditions

hashtagCondition Types

hashtagUnderstanding Permission Behavior

hashtagHow Permissions Are Checked

hashtagWhat Happens When Permissions Are Missing

hashtagRole Hierarchy Requirements

hashtagCommon Role Examples

hashtagContent Moderator

hashtagRead-Only User

hashtagBest Practices

hashtagStart Simple

hashtagUse Organization Scoping

hashtagPrefer Allow Over Deny

hashtagTest Permission Changes

hashtagDocument Your Roles

What You'll Learn

Getting Started

Basic Concepts

Working with Role APIs

Get roles

Create a role

Modify a role

Assign a role to user

Creating Permission Rules

Permission Names

Adding Conditions

Condition Types

Understanding Permission Behavior

How Permissions Are Checked

What Happens When Permissions Are Missing

Role Hierarchy Requirements

Common Role Examples

Content Moderator

Read-Only User

Best Practices

Start Simple

Use Organization Scoping

Prefer Allow Over Deny

Test Permission Changes

Document Your Roles