Go to website

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

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
Path parameters
organizationstringRequired
Query parameters
return_permission_grantsbooleanOptional

Whether to return permission grants.

Default: false
idstring[]Optional

The ID of the role to get.

Default: []
namestring[]Optional

The name of the role to get.

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
or
nullOptional
Responses
200
Succeeded
application/json
get
GET /v1/{organization}/role/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Accept: */*

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

Create a role

post

Create a new role.

Permissions

This endpoint requires the following permissions:

  • Role:CreateRole for the role.
Authorizations
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
or
nullOptional
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:
is_base_rolebooleanRequired

Whether this role is a base role. Base roles cannot inherit from other roles. One can only inherit from base roles.

inherited_fromany ofRequired

The ID of the role that this role inherits from.

stringOptionalPattern: ^[a-f0-9]{24}$
or
nullOptional
Responses
201
Succeeded
application/json
post
POST /v1/{organization}/role/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 269

{
  "role_name": "text",
  "description": "text",
  "permission_grants": [
    {
      "action": "Allow",
      "permission_name": "text",
      "conditions": {
        "ANY_ADDITIONAL_PROPERTY": {
          "type": "Equals",
          "value": null
        }
      },
      "description": "text"
    }
  ],
  "frontend_view": "client",
  "is_base_role": true,
  "inherited_from": "text"
}
{
  "role_id": "text"
}

Modify a role

post

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.

If a base role is updated, all of its dependent roles will also be updated (by creating a new version of it), and all users/API keys assigned to the role will be switched to the new role.

Permissions

This endpoint requires the following permissions:

  • Role:ModifyRole for the role and, if it's a base role, all of its dependent roles.

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
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
or
nullOptional
Body
descriptionany ofOptional

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

string · min: 1Optional
or
nullOptional
permission_grantsany ofOptional

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

or
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:
or
nullOptional
inherited_fromany ofOptional

The ID of the role that this role inherits from. Only updated if specified. This field is an immutable field.

Default: {}
stringOptionalPattern: ^[a-f0-9]{24}$
or
object · _NotSetOptional

A specific type to indicate that a field is not set in the request.

or
nullOptional
Responses
200
Succeeded
application/json
post
POST /v1/{organization}/role/{role_name} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 230

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

Assign a role to user

post

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
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
or
nullOptional
Body
user_idstringRequired

The identifier of the user to assign the role to.

Responses
200
Succeeded
application/json
post
POST /v1/{organization}/role/{role_name}/assign HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
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:GetUser - 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: You can use {self_org_id} in condition values to automatically reference the user's organization.

Understanding Permission Behavior

How Permissions Are Checked

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

  1. Looks at all permission grants in the user's role

  2. Finds grants that match the action being attempted

  3. Checks if any conditions are met

  4. Deny grants always win - if any deny grant matches, the action is blocked

  5. 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 can't view service details, service_name fields might be empty

  • 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 view and moderate conversations but not create them:

{
    "role_name": "content_moderator",
    "description": "Can view and moderate conversations in their organization",
    "is_base_role": false,
    "frontend_view": "standard",
    "permission_grants": [
        {
            "action": "Allow",
            "permission_name": "Conversation:GetConversation",
            "conditions": {
                "org_id": {"type": "Equals", "value": "{self_org_id}"}
            },
            "description": "View conversations in own organization"
        },
        {
            "action": "Allow", 
            "permission_name": "Conversation:ModifyConversation",
            "conditions": {
                "org_id": {"type": "Equals", "value": "{self_org_id}"},
                "action_type": {"type": "In", "values": ["hide", "flag"]}
            },
            "description": "Hide or flag conversations in own organization"
        }
    ]
}

Read-Only User

A role that can only view data, never modify it:

{
    "role_name": "viewer",
    "description": "Can only view data, cannot create or modify",
    "is_base_role": false,
    "frontend_view": "standard",
    "permission_grants": [
        {
            "action": "Allow",
            "permission_name": "Conversation:GetConversation",
            "conditions": {
                "org_id": {"type": "Equals", "value": "{self_org_id}"}
            },
            "description": "View conversations in own organization"
        },
        {
            "action": "Deny",
            "permission_name": "Conversation:CreateConversation",
            "conditions": {},
            "description": "Cannot create new 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.

PreviousData Retrieval + User Model ManagementNextWebhook Management

Last updated

Was this helpful?