LogoLogo
Go to website
  • Welcome
  • Getting Started
    • Amigo Overview
      • System Components
      • Overcoming LLM Limitations
      • [Advanced] Future-Ready Architecture
      • [Advanced] The Accelerating AI Landscape
    • The Journey with Amigo
      • Partnership Model
  • Concepts
    • Agent Core
      • Core Persona
      • Global Directives
    • Context Graphs
      • State-Based Architecture
      • [Advanced] Field Implementation Guidance
    • Functional Memory
      • Layered Architecture
      • User Model
      • [Advanced] Recall Mechanisms
      • [Advanced] Analytical Capabilities
    • Dynamic Behaviors
      • Side-Effect Architecture
      • Knowledge
      • [Advanced] Behavior Chaining
    • Evaluations
      • Testing Framework Examples
    • [Advanced] Reinforcement Learning
    • Safety
  • Glossary
  • Advanced Topics
    • Transition to Neuralese Systems
    • Agent V2 Architecture
  • Agent Building Best Practices
    • Dynamic Behaviors Guide
  • Developer Guide
    • Enterprise Integration Guide
      • Authentication
      • User Creation + Management
      • Service Discovery + Management
      • Conversation Creation + Management
      • Data Retrieval + User Model Management
      • Webhook Management
    • API Reference
      • V1/organization
      • V1/service
      • V1/conversation
      • V1/user
      • V1/role
      • V1/admin
      • V1/webhook_destination
      • V1/metric
      • V1/dynamic_behavior_set
      • V1/simulation
      • Models
Powered by GitBook
LogoLogo

Resources

  • Pricing
  • About Us

Company

  • Careers

Policies

  • Terms of Service

Amigo Inc. ©2025 All Rights Reserved.


On this page

Was this helpful?

Export as PDF
  1. Developer Guide
  2. API Reference

V1/role

PreviousV1/userNextV1/admin

Was this helpful?

  • GETGet roles
  • POSTCreate a role
  • POSTModify a role
  • POSTAssign a role to user

Get roles

get

Return a list of roles in this organization.

Permissions

This endpoint requires the following permissions:

  • User:GetUserInfo for the authenticated user.

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
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
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": "text",
              "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:

  • User:GetUserInfo for the authenticated user.

  • 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
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
POST /v1/{organization}/role/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 267

{
  "role_name": "text",
  "description": "text",
  "permission_grants": [
    {
      "action": "Allow",
      "permission_name": "text",
      "conditions": {
        "ANY_ADDITIONAL_PROPERTY": {
          "type": "text",
          "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
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
POST /v1/{organization}/role/{role_name} HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 228

{
  "description": "text",
  "permission_grants": [
    {
      "action": "Allow",
      "permission_name": "text",
      "conditions": {
        "ANY_ADDITIONAL_PROPERTY": {
          "type": "text",
          "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:

  • User.GetUserInfo for the authenticated user.

  • 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
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
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"
}