Role

Get roles

get

https://api.amigo.aihttps://internal-api.amigo.aihttps://api-eu-central-1.amigo.aihttps://api-ap-southeast-2.amigo.aihttps://api-ca-central-1.amigo.ai

/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

Bearer-Authorization & Bearer-Authorization-Organization

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

or

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/

HTTPcURLJavaScriptPython

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": [
        {
          "action": "Allow",
          "permission_name": "text",
          "conditions": {
            "ANY_ADDITIONAL_PROPERTY": {
              "type": "Equals",
              "value": null
            }
          },
          "description": "text"
        }
      ]
    }
  ]
}

Create a role

post

https://api.amigo.aihttps://internal-api.amigo.aihttps://api-eu-central-1.amigo.aihttps://api-ap-southeast-2.amigo.aihttps://api-ca-central-1.amigo.ai

/v1/{organization}/role/

Create a new role.

Permissions

This endpoint requires the following permissions:

• Role:CreateRole for the role.

Authorizations

Bearer-Authorization & Bearer-Authorization-Organization

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

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

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

application/json

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/

HTTPcURLJavaScriptPython

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: 225

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

{
  "role_id": "text"
}

Modify a role

post

https://api.amigo.aihttps://internal-api.amigo.aihttps://api-eu-central-1.amigo.aihttps://api-ap-southeast-2.amigo.aihttps://api-ca-central-1.amigo.ai

/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

Bearer-Authorization & Bearer-Authorization-Organization

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

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

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

application/json

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

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

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

HTTPcURLJavaScriptPython

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: 206

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

{
  "role_id": "text"
}

Assign a role to user

post

https://api.amigo.aihttps://internal-api.amigo.aihttps://api-eu-central-1.amigo.aihttps://api-ap-southeast-2.amigo.aihttps://api-ca-central-1.amigo.ai

/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

Bearer-Authorization & Bearer-Authorization-Organization

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

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

Sec-WebSocket-Protocolstring[]OptionalDefault: []

Body

application/json

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

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

HTTPcURLJavaScriptPython

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