Role
Create a new temporary permission grant.
The user that is given the grant will be able to perform actions permitted by the grant for a limited amount of time. Note that any actions that require comparing the permissions of the user and the permissions of another entity would still use the user and the other entity's role, without factoring into the temporary permission grants.
Permissions
This endpoint requires the following permissions:
Role:CreateTemporaryPermissionGrantfor the grant to create.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
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.
[]The ID of the user to grant the temporary permission to.
In ISO8601 format, the duration that this permission grant will last.
A justification for why this grant is made.
Succeeded
The ID of the created temporary permission grant.
The time in UTC at which the permission grant expires.
Invalid authorization credentials.
Missing required permissions.
Specified organization or user is not found.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 100 requests per minute for this endpoint.
The service is going through temporary maintenance.
POST /v1/{organization}/role/temporary_permission_grant/ 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: 219
{
"user_id": "text",
"duration": "text",
"permission_grant": {
"permission_name": "text",
"conditions": {
"ANY_ADDITIONAL_PROPERTY": {
"type": "Equals",
"value": null
}
}
},
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"justification": "text"
}{
"temporary_permission_grant_id": "text",
"expires_at": "2026-01-01T00:00:00.000Z"
}Retrieve the temporary permission grants that match the given filters.
Permissions
This endpoint may be impacted by the following permissions:
Only temporary permission grants that the authenticated user has
Role:GetTemporaryPermissionGrantpermission for will be returned.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The IDs of the temporary permission grants to retrieve.
[]The user IDs of the temporary permission grants to retrieve.
[]The permission name of the grants.
Whether to only return expired or unexpired temporary permission grants.
The maximum number of temporary permission grants to return.
10The continuation token to use to retrieve the next set of temporary permission grants.
0The creators of the temporary permission grants.
[]The tags of the temporary permission grants. Must be specified using the syntax key:value, which means to match all sets with the given key and value pair among its tags. If value is *, it means the value does not matter. If value is empty, it matches against when the value is None.
[]The fields to sort the sets by. Supported fields are user_id, expires_at, and permission_grant.permission_name. Specify a + before the field name to indicate ascending sorting and - for descending sorting. Multiple fields can be specified to break ties.
[]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.
[]Succeeded.
Whether there are more temporary permission grants to retrieve.
The continuation token to use to retrieve the next set of temporary permission grants.
Invalid authorization credentials.
Missing required permissions.
Specified organization is not found.
Invalid request path parameter or request query parameter failed validation.
The user has exceeded the rate limit of 100 requests per minute for this endpoint.
The service is going through temporary maintenance.
GET /v1/{organization}/role/temporary_permission_grants/ HTTP/1.1
Host: api.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-ORG-ID: YOUR_API_KEY
Accept: */*
{
"temporary_permission_grants": [
{
"_id": "text",
"org_id": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"user_id": "text",
"expires_at": "2026-01-01T00:00:00.000Z",
"permission_grant": {
"permission_name": "text",
"conditions": {
"ANY_ADDITIONAL_PROPERTY": {
"type": "Equals",
"value": null
}
}
},
"justification": "text",
"creator": {
"org_id": "text",
"user_id": "text"
},
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
],
"has_more": true,
"continuation_token": 1
}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:GetRolepermission on will be returned.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
Whether to return permission grants.
falseThe IDs of the roles to retrieve.
[]The names of the roles to retrieve.
[]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.
[]Succeeded
Invalid authorization credentials.
Missing required permissions.
Specified organization is not found.
Invalid request path parameter or request query parameter failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
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 new role.
Permissions
This endpoint requires the following permissions:
Role:CreateRolefor the role.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
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.
[]The name of the role to create. The role must have a max length of 256 characters.
A description about the role.
The frontend view for users of this role.
Succeeded
The ID of the newly created role.
Invalid authorization credentials.
Missing required permissions.
Specified organization or inherited role is not found.
Role with the same name already exists in this organization.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 20 requests per minute for this endpoint.
The service is going through temporary maintenance.
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 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:ModifyRolefor 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.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The name of the role.
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.
[]A description about the role. Only updated if specified. This field is a mutable field.
The frontend view for the user of this role. Only updated if specified. This field is an immutable field.
Succeeded
The identifier of the updated role.
Base roles cannot inherit from other roles.
Invalid authorization credentials.
Missing required permissions.
Specified organization, role, or inherited role is not found.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 10 requests per minute for this endpoint.
The service is going through temporary maintenance.
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 a user.
Permissions
This endpoint requires the following permissions:
The authenticated user to have greater privileges than the role being assigned.
The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.
Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the SignInWithAPIKey endpoint.
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.
The name of the role to assign.
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.
[]The identifier of the user to assign the role to.
Succeeded
The identifier of the role assigned to the user.
Invalid authorization credentials.
Missing required permissions.
Specified organization, role, or user is not found.
Invalid request path parameter or request body failed validation.
The user has exceeded the rate limit of 1000 requests per minute for this endpoint.
The service is going through temporary maintenance.
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"
}Last updated
Was this helpful?