Role Assignments are RBAC-constructs that state that a actor (i.e: user) is assigned a role within a tenant. With role assignments you can assign or unassign roles to a user. Role assignment define the relationship between users and tenants.
openapi: 3.1.0
info:
title: Permit.io Access Requests (EAP) Access Requests (EAP) Role Assignments API
description: '
Authorization as a service
'
version: 2.0.0
tags:
- name: Role Assignments
description: '
Role Assignments are RBAC-constructs that state that a actor (i.e: user) is assigned a role within a tenant.
With role assignments you can assign or unassign roles to a user.
Role assignment define the relationship between users and tenants.
'
paths:
/v2/facts/{proj_id}/{env_id}/role_assignments/detailed:
get:
tags:
- Role Assignments
summary: List Role Assignments Detailed
description: 'Lists the role assignments defined within an environment.
- If the `user` filter is present, will only return the role assignments of that user (supports multiple).
- If the `tenant` filter is present, will only return the role assignments in that tenant (supports multiple).
- If the `role` filter is present, will only return role assignments that are granting that role (supports multiple).
- If the `resource` filter is present, will only return role assignments for resource instances of that resource type.
- If the `resource_instance` filter is present, will only return role assignments for that resource instance.
Providing both `tenant` and `resource_instance` filters will only return role assignments if the resource instance is in that tenant.
If multiple tenants are received, the last tenant will be compared with the resource instance.'
operationId: list_role_assignments_detailed
parameters:
- description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
required: true
schema:
type: string
title: Proj Id
description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
example: my_project
name: proj_id
in: path
- description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
required: true
schema:
type: string
title: Env Id
description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
example: my_environment
name: env_id
in: path
- description: optional user(s) filter, will only return role assignments granted to this user(s).
required: false
schema:
items:
type: string
type: array
title: User
description: optional user(s) filter, will only return role assignments granted to this user(s).
name: user
in: query
- description: optional role(s) filter, will only return role assignments granting this role(s).
required: false
schema:
items:
type: string
type: array
title: Role
description: optional role(s) filter, will only return role assignments granting this role(s).
name: role
in: query
- description: optional tenant(s) filter, will only return role assignments granted in that tenant(s).
required: false
schema:
items:
type: string
type: array
title: Tenant
description: optional tenant(s) filter, will only return role assignments granted in that tenant(s).
name: tenant
in: query
- description: optional resource **type** filter, will only return role assignments granted on that resource type.
required: false
schema:
type: string
title: Resource
description: optional resource **type** filter, will only return role assignments granted on that resource type.
name: resource
in: query
- description: optional resource instance filter, will only return role assignments granted on that resource instance.
required: false
schema:
type: string
title: Resource Instance
description: optional resource instance filter, will only return role assignments granted on that resource instance.
name: resource_instance
in: query
- description: Page number of the results to fetch, starting at 1.
required: false
schema:
type: integer
minimum: 1.0
title: Page
description: Page number of the results to fetch, starting at 1.
default: 1
name: page
in: query
- description: The number of results per page (max 1000).
required: false
schema:
type: integer
maximum: 1000.0
minimum: 1.0
title: Per Page
description: The number of results per page (max 1000).
default: 30
name: per_page
in: query
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedResult_RoleAssignmentDetailedRead_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/facts/{proj_id}/{env_id}/role_assignments:
get:
tags:
- Role Assignments
summary: List Role Assignments
description: 'Lists the role assignments defined within an environment.
- If the `user` filter is present, will only return the role assignments of that user (supports multiple).
- If the `tenant` filter is present, will only return the role assignments in that tenant (supports multiple).
- If the `role` filter is present, will only return role assignments that are granting that role (supports multiple).
- If the `resource` filter is present, will only return role assignments for resource instances of that resource type.
- If the `resource_instance` filter is present, will only return role assignments for that resource instance.
Providing both `tenant` and `resource_instance` filters will only return role assignments if the resource instance is in that tenant.
If multiple tenants are received, the last tenant will be compared with the resource instance.'
operationId: list_role_assignments
parameters:
- description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
required: true
schema:
type: string
title: Proj Id
description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
example: my_project
name: proj_id
in: path
- description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
required: true
schema:
type: string
title: Env Id
description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
example: my_environment
name: env_id
in: path
- description: optional user(s) filter, will only return role assignments granted to this user(s).
required: false
schema:
items:
type: string
type: array
title: User
description: optional user(s) filter, will only return role assignments granted to this user(s).
name: user
in: query
- description: optional role(s) filter, will only return role assignments granting this role(s).
required: false
schema:
items:
type: string
type: array
title: Role
description: optional role(s) filter, will only return role assignments granting this role(s).
name: role
in: query
- description: optional tenant(s) filter, will only return role assignments granted in that tenant(s).
required: false
schema:
items:
type: string
type: array
title: Tenant
description: optional tenant(s) filter, will only return role assignments granted in that tenant(s).
name: tenant
in: query
- description: optional resource **type** filter, will only return role assignments granted on that resource type.
required: false
schema:
type: string
title: Resource
description: optional resource **type** filter, will only return role assignments granted on that resource type.
name: resource
in: query
- description: optional resource instance filter, will only return role assignments granted on that resource instance.
required: false
schema:
type: string
title: Resource Instance
description: optional resource instance filter, will only return role assignments granted on that resource instance.
name: resource_instance
in: query
- description: Whether to return full details about the user, tenant and role
required: false
deprecated: true
schema:
type: boolean
title: Detailed
description: Whether to return full details about the user, tenant and role
default: false
name: detailed
in: query
- description: If true, returns the list of role assignments and the total count.
required: false
deprecated: true
schema:
type: boolean
title: Include Total Count
description: If true, returns the list of role assignments and the total count.
default: false
name: include_total_count
in: query
- description: Page number of the results to fetch, starting at 1.
required: false
schema:
type: integer
minimum: 1.0
title: Page
description: Page number of the results to fetch, starting at 1.
default: 1
name: page
in: query
- description: The number of results per page (max 1000).
required: false
schema:
type: integer
maximum: 1000.0
minimum: 1.0
title: Per Page
description: The number of results per page (max 1000).
default: 30
name: per_page
in: query
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- items:
$ref: '#/components/schemas/RoleAssignmentRead'
type: array
- $ref: '#/components/schemas/PaginatedResult_RoleAssignmentRead_'
- items:
$ref: '#/components/schemas/RoleAssignmentDetailedRead'
type: array
- $ref: '#/components/schemas/PaginatedResult_RoleAssignmentDetailedRead_'
title: Response List Role Assignments V2 Facts Proj Id Env Id Role Assignments Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
post:
tags:
- Role Assignments
summary: Assign Role
description: 'Assigns a role to a user within a tenant.
The tenant defines the scope of the assignment. In other words, the role is effective only within the tenant.'
operationId: assign_role
parameters:
- description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
required: true
schema:
type: string
title: Proj Id
description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
example: my_project
name: proj_id
in: path
- description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
required: true
schema:
type: string
title: Env Id
description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
example: my_environment
name: env_id
in: path
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RoleAssignmentCreate'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoleAssignmentRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
delete:
tags:
- Role Assignments
summary: Unassign Role
description: 'Unassigns a user role within a tenant.
The tenant defines the scope of the assignment. In other words, the role is effective only within the tenant.
If the role is not actually assigned, will return 404.'
operationId: unassign_role
parameters:
- description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
required: true
schema:
type: string
title: Proj Id
description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
example: my_project
name: proj_id
in: path
- description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
required: true
schema:
type: string
title: Env Id
description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
example: my_environment
name: env_id
in: path
- description: Whether to return the deleted role assignment, status code will be 200 instead of the default 204 if true
required: false
deprecated: true
schema:
type: boolean
title: Return Deleted
description: Whether to return the deleted role assignment, status code will be 200 instead of the default 204 if true
default: false
name: return_deleted
in: query
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RoleAssignmentRemove'
required: true
responses:
'200':
description: Role assignment removed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/RoleAssignmentRead'
'204':
description: Role assignment removed successfully
'404':
description: Role assignment not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/facts/{proj_id}/{env_id}/role_assignments/bulk:
post:
tags:
- Role Assignments
summary: Bulk create role assignments
operationId: bulk_assign_role
parameters:
- description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
required: true
schema:
type: string
title: Proj Id
description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
example: my_project
name: proj_id
in: path
- description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
required: true
schema:
type: string
title: Env Id
description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
example: my_environment
name: env_id
in: path
- description: 'Policy for missing users - ''fail'': Fail the entire operation if a user is missing; ''ignore'': Skip assignments for missing users; ''create'': Create missing users and continue with the operation'
required: false
schema:
allOf:
- $ref: '#/components/schemas/MissingUserPolicy'
description: 'Policy for missing users - ''fail'': Fail the entire operation if a user is missing; ''ignore'': Skip assignments for missing users; ''create'': Create missing users and continue with the operation'
default: fail
name: missing_user_policy
in: query
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/RoleAssignmentCreate'
type: array
title: Role Assignments In
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BulkRoleAssignmentReport'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
delete:
tags:
- Role Assignments
summary: Bulk Unassign Role
operationId: bulk_unassign_role
parameters:
- description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
required: true
schema:
type: string
title: Proj Id
description: 'Either the unique id of the project, or the URL-friendly key of the project (i.e: the "slug").'
example: my_project
name: proj_id
in: path
- description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
required: true
schema:
type: string
title: Env Id
description: 'Either the unique id of the environment, or the URL-friendly key of the environment (i.e: the "slug").'
example: my_environment
name: env_id
in: path
requestBody:
content:
application/json:
schema:
items:
$ref: '#/components/schemas/RoleAssignmentRemove'
type: array
title: Role Assignment In
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BulkRoleUnAssignmentReport'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
RoleAssignmentRole:
properties:
id:
type: string
format: uuid
title: Id
key:
type: string
title: Key
name:
type: string
title: Name
permissions:
items:
type: string
type: array
title: Permissions
additionalProperties: false
type: object
required:
- id
- key
- name
title: RoleAssignmentRole
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
RoleAssignmentDetailedRead:
properties:
id:
type: string
format: uuid
title: Id
description: Unique id of the role assignment
role:
allOf:
- $ref: '#/components/schemas/RoleAssignmentRole'
title: Role
description: the role that is assigned
user:
allOf:
- $ref: '#/components/schemas/RoleAssignmentUser'
title: User
description: the user the role is assigned to
tenant:
allOf:
- $ref: '#/components/schemas/RoleAssignmentTenant'
title: Tenant
description: the tenant the role is associated with
resource_instance:
$ref: '#/components/schemas/RoleAssignmentResourceInstance'
organization_id:
type: string
format: uuid
title: Organization Id
description: Unique id of the organization that the role assignment belongs to.
project_id:
type: string
format: uuid
title: Project Id
description: Unique id of the project that the role assignment belongs to.
environment_id:
type: string
format: uuid
title: Environment Id
description: Unique id of the environment that the role assignment belongs to.
created_at:
type: string
format: date-time
title: Created At
description: Date and time when the role assignment was created (ISO_8601 format).
additionalProperties: false
type: object
required:
- id
- role
- user
- tenant
- organization_id
- project_id
- environment_id
- created_at
title: RoleAssignmentDetailedRead
RoleAssignmentRead:
properties:
id:
type: string
format: uuid
title: Id
description: Unique id of the role assignment
user:
type: string
title: User
description: the user the role is assigned to
role:
type: string
title: Role
description: the role that is assigned
tenant:
type: string
title: Tenant
description: the tenant the role is associated with
resource_instance:
type: string
title: Resource Instance
description: the resource instance the role is associated with
resource_instance_id:
type: string
format: uuid
title: Resource Instance Id
description: Unique id of the resource instance
user_id:
type: string
format: uuid
title: User Id
description: Unique id of the user
role_id:
type: string
format: uuid
title: Role Id
description: Unique id of the role
tenant_id:
type: string
format: uuid
title: Tenant Id
description: Unique id of the tenant
organization_id:
type: string
format: uuid
title: Organization Id
description: Unique id of the organization that the role assignment belongs to.
project_id:
type: string
format: uuid
title: Project Id
description: Unique id of the project that the role assignment belongs to.
environment_id:
type: string
format: uuid
title: Environment Id
description: Unique id of the environment that the role assignment belongs to.
created_at:
type: string
format: date-time
title: Created At
description: Date and time when the role assignment was created (ISO_8601 format).
additionalProperties: false
type: object
required:
- id
- user
- role
- user_id
- role_id
- tenant_id
- organization_id
- project_id
- environment_id
- created_at
title: RoleAssignmentRead
example:
id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
user: jane@coolcompany.com
role: admin
tenant: stripe-inc
user_id: 7c60d51f-b44e-4682-87d6-449835ea4d11
role_id: 405d8375-3514-403b-8c43-83ae74cfe022
tenant_id: 40ef0e48-a11f-4963-a229-e396c9f7e733
organization_id: 7c60d51f-b44e-4682-87d6-449835ea4de6
project_id: 405d8375-3514-403b-8c43-83ae74cfe0e9
environment_id: 40ef0e48-a11f-4963-a229-e396c9f7e7c4
created_at: '2019-08-24T14:15:22Z'
RoleAssignmentUser:
properties:
id:
type: string
format: uuid
title: Id
key:
type: string
title: Key
email:
type: string
title: Email
first_name:
type: string
title: First Name
last_name:
type: string
title: Last Name
attributes:
type: object
title: Attributes
default: {}
additionalProperties: false
type: object
required:
- id
- key
title: RoleAssignmentUser
BulkRoleAssignmentReport:
properties:
assignments_created:
type: integer
title: Assignments Created
default: 0
additionalProperties: false
type: object
title: BulkRoleAssignmentReport
PaginatedResult_RoleAssignmentRead_:
properties:
data:
items:
$ref: '#/components/schemas/RoleAssignmentRead'
type: array
title: Data
description: List of Role Assignments
total_count:
type: integer
minimum: 0.0
title: Total Count
page_count:
type: integer
minimum: 0.0
title: Page Count
default: 0
additionalProperties: false
type: object
required:
- data
- total_count
title: PaginatedResult[RoleAssignmentRead]
MissingUserPolicy:
type: string
enum:
- fail
- ignore
- create
title: MissingUserPolicy
description: An enumeration.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
RoleAssignmentTenant:
properties:
id:
type: string
format: uuid
title: Id
key:
type: string
title: Key
name:
type: string
title: Name
attributes:
type: object
title: Attributes
default: {}
additionalProperties: false
type: object
required:
- id
- key
- name
title: RoleAssignmentTenant
RoleAssignmentCreate:
properties:
role:
type: string
title: Role
description: the role that will be assigned (accepts either the role id or the role key)
tenant:
type: string
title: Tenant
description: the tenant the role is associated with (accepts either the tenant id or the tenant key)
resource_instance:
type: string
title: Resource Instance
description: the resource instance the role is associated with (accepts either the resource instance id or key using this format resource_type:resource_instance)The resource instance will be implicitly created if the tenant parameter is specified and the resource instance does not exist.
user:
type: string
title: User
description: the user the role will be assigned to (accepts either the user id or the user key)
additionalProperties: false
type: object
required:
- role
- user
title: RoleAssignmentCreate
example:
user: jane@coolcompany.com
role: admin
tenant: stripe-inc
PaginatedResult_RoleAssignmentDetailedRead_:
properties:
data:
items:
$ref: '#/components/schemas/RoleAssignmentDetailedRead'
type: array
title: Data
description: List of Role Assignment Detaileds
total_count:
type: integer
minimum: 0.0
title: Total Count
page_count:
type: integer
minimum: 0.0
title: Page Count
default: 0
additionalProperties: false
type: object
required:
- data
- total_count
title: PaginatedResult[RoleAssignmentDetailedRead]
BulkRoleUnAssignmentReport:
properties:
assignments_removed:
type: integer
title: Assignments Removed
default: 0
additionalProperties: false
type: object
title: BulkRoleUnAssignmentReport
RoleAssignmentRemove:
properties:
role:
type: string
title: Role
description: the role that will be unassigned (accepts either the role id or the role key)
tenant:
type: string
title: Tenant
description: the tenant the role is associated with (accepts either the tenant id or the tenant key)
resource_instance:
type: string
title: Resource Instance
description: the resource instance the role is associated with (accepts either the resource instance id or key using this format resource_type:resource_instance)
user:
type: string
title: User
description: the user the role will be unassigned from (accepts either the user id or the user key)
additionalProperties: false
type: object
required:
- role
- tenant
- user
title: RoleAssignmentRemove
example:
user: jane@coolcompany.com
role: editor
tenant: google-inc
RoleAssignmentResourceInstance:
properties:
id:
type: string
format: uuid
title: Id
key:
type: string
title: Key
resource:
type: string
title: Resource
attributes:
type: object
title: Attributes
default: {}
additionalProperties: false
type: object
required:
- id
- key
- resource
title: RoleAssignmentResourceInstance
securitySchemes:
HTTPBearer:
type: http
description: 'Authorization header, we support the bearer authentication scheme (see: RFC 6750)'
scheme: bearer
bearerFormat: JWT