Roles allow you to associate permissions indirectly via a job function. The Roles API allows you to manipulate roles: assign or unassign permissions to a role, define hierarchy between roles or define relationships between resource roles. Roles manipulated by this API are **tenant roles**, meaning when they are assigned, they are assigned on a tenant.
openapi: 3.1.0
info:
title: Permit.io Access Requests (EAP) Access Requests (EAP) Roles API
description: '
Authorization as a service
'
version: 2.0.0
tags:
- name: Roles
description: '
Roles allow you to associate permissions indirectly via a job function.
The Roles API allows you to manipulate roles: assign or unassign permissions to a role,
define hierarchy between roles or define relationships between resource roles.
Roles manipulated by this API are **tenant roles**, meaning when they are assigned, they are
assigned on a tenant.
'
paths:
/v2/schema/{proj_id}/{env_id}/roles:
get:
tags:
- Roles
summary: List Roles
description: Lists all tenant roles.
operationId: list_roles
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: Include total count in response
required: false
deprecated: true
schema:
type: boolean
title: Include Total Count
description: Include total count in response
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 100).
required: false
schema:
type: integer
maximum: 100.0
minimum: 1.0
title: Per Page
description: The number of results per page (max 100).
default: 30
name: per_page
in: query
- description: Text search for the object name or key
required: false
schema:
type: string
title: Search
description: Text search for the object name or key
name: search
in: query
responses:
'200':
description: Successful Response
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/PaginatedResult_RoleRead_'
- items:
$ref: '#/components/schemas/RoleRead'
type: array
title: Response List Roles V2 Schema Proj Id Env Id Roles Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
post:
tags:
- Roles
summary: Create Role
description: Creates a new tenant role.
operationId: create_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/RoleCreate'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoleRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/schema/{proj_id}/{env_id}/roles/{role_id}:
get:
tags:
- Roles
summary: Get Role
description: Gets a single tenant role, if such role exists.
operationId: get_role
parameters:
- description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
required: true
schema:
type: string
title: Role Id
description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
name: role_id
in: path
- 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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoleRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
delete:
tags:
- Roles
summary: Delete Role
description: 'Deletes a tenant role and all its related data.
This includes any permissions granted to said role.'
operationId: delete_role
parameters:
- description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
required: true
schema:
type: string
title: Role Id
description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
name: role_id
in: path
- 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
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
patch:
tags:
- Roles
summary: Update Role
description: 'Partially updates a tenant role.
Fields that will be provided will be completely overwritten.'
operationId: update_role
parameters:
- description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
required: true
schema:
type: string
title: Role Id
description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
name: role_id
in: path
- 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/RoleUpdate'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoleRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/schema/{proj_id}/{env_id}/roles/{role_id}/permissions:
post:
tags:
- Roles
summary: Assign Permissions To Role
description: 'Assign permissions to role.
If some of the permissions specified are already assigned, will skip them.'
operationId: assign_permissions_to_role
parameters:
- description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
required: true
schema:
type: string
title: Role Id
description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
name: role_id
in: path
- 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/AddRolePermissions'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoleRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
delete:
tags:
- Roles
summary: Remove Permissions From Role
description: 'Remove permissions from role.
If some of the permissions specified are already unassigned, will skip them.'
operationId: remove_permissions_from_role
parameters:
- description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
required: true
schema:
type: string
title: Role Id
description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
name: role_id
in: path
- 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/RemoveRolePermissions'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoleRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/schema/{proj_id}/{env_id}/roles/{role_id}/ancestors:
get:
tags:
- Roles
summary: Get Role Ancestors
operationId: get_role_ancestors
parameters:
- description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
required: true
schema:
type: string
title: Role Id
description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
name: role_id
in: path
- 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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoleList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/schema/{proj_id}/{env_id}/roles/{role_id}/descendants:
get:
tags:
- Roles
summary: Get Role Descendants
operationId: get_role_descendants
parameters:
- description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
required: true
schema:
type: string
title: Role Id
description: 'Either the unique id of the role, or the URL-friendly key of the role (i.e: the "slug").'
name: role_id
in: path
- 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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RoleList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
permit_backend__schemas__schema_derived_role_rule__DerivationSettings:
properties:
no_direct_roles_on_object:
type: boolean
title: No Direct Roles On Object
description: If true, the derived role or the specific rule will not apply if the resource has any direct role
default: false
additionalProperties: false
type: object
title: DerivationSettings
description: Settings for a derived role or a derived role rule
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
DerivedRoleBlockRead:
properties:
when:
allOf:
- $ref: '#/components/schemas/permit_backend__schemas__schema_derived_role_rule__DerivationSettings'
title: When
description: the settings of the derived role
default:
no_direct_roles_on_object: false
id:
type: string
format: uuid
title: Id
description: The unique id of the derived_role
users_with_role:
items:
$ref: '#/components/schemas/DerivedRoleRuleRead'
type: array
title: Users With Role
description: the rules of the derived role
default: []
additionalProperties: false
type: object
required:
- id
title: DerivedRoleBlockRead
example:
id: 970eb6a2-af5a-4173-b291-dbbc00d8b5e3
users_with_role:
- role: Admin
on_resource: organization
linked_by_relation: owner
role_id: 7a972455-b010-4649-badb-08fe265490a0
resource_id: 12359938-c5ff-42ca-af2d-3024f92bd0be
relation_id: fe1ea573-34ef-4969-a3c4-284ae998045f
DerivedRoleRuleCreate:
properties:
role:
type: string
title: Role
description: the role key that needs to exist on the related resource (from the relation)
on_resource:
type: string
title: On Resource
description: the resource key that needs to exist on the related role (from the relation)
linked_by_relation:
type: string
title: Linked By Relation
description: the relation key that needs to exist between the resource and the related resource
when:
allOf:
- $ref: '#/components/schemas/permit_backend__schemas__schema_derived_role_rule__DerivationSettings'
title: When
description: the settings of the derived role rule
default:
no_direct_roles_on_object: false
additionalProperties: false
type: object
required:
- role
- on_resource
- linked_by_relation
title: DerivedRoleRuleCreate
example:
role: Admin
on_resource: organization
linked_by_relation: owner
RoleList:
properties:
roles:
anyOf:
- items:
$ref: '#/components/schemas/RoleRead'
type: array
- $ref: '#/components/schemas/PaginatedResult_RoleRead_'
title: Roles
additionalProperties: false
type: object
required:
- roles
title: RoleList
AddRolePermissions:
properties:
permissions:
items:
type: string
type: array
title: Permissions
description: 'List of permissions to assign to the role. If a permission is already granted to the role it is skipped. Each permission can be either a resource action id, or `{resource_key}:{action_key}`, i.e: the "permission name".'
additionalProperties: false
type: object
required:
- permissions
title: AddRolePermissions
example:
permissions:
- document:write
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
DerivedRoleRuleRead:
properties:
role_id:
type: string
format: uuid
title: Role Id
description: the role id that needs to exist on the related resource (from the relation)
resource_id:
type: string
format: uuid
title: Resource Id
description: the resource id that needs to exist on the related role (from the relation)
relation_id:
type: string
format: uuid
title: Relation Id
description: the relation id that needs to exist between the resource and the related resource
role:
type: string
title: Role
description: the role key that needs to exist on the related resource (from the relation)
on_resource:
type: string
title: On Resource
description: the resource key that needs to exist on the related role (from the relation)
linked_by_relation:
type: string
title: Linked By Relation
description: the relation key that needs to exist between the resource and the related resource
when:
allOf:
- $ref: '#/components/schemas/permit_backend__schemas__schema_derived_role_rule__DerivationSettings'
title: When
description: the settings of the derived role rule
default:
no_direct_roles_on_object: false
additionalProperties: false
type: object
required:
- role_id
- resource_id
- relation_id
- role
- on_resource
- linked_by_relation
title: DerivedRoleRuleRead
example:
role: Admin
on_resource: organization
linked_by_relation: owner
role_id: 7a972455-b010-4649-badb-08fe265490a0
resource_id: 12359938-c5ff-42ca-af2d-3024f92bd0be
relation_id: fe1ea573-34ef-4969-a3c4-284ae998045f
RoleUpdate:
properties:
name:
type: string
title: Name
description: The name of the role
description:
type: string
title: Description
description: optional description string explaining what this role represents, or what permissions are granted to it.
permissions:
items:
type: string
type: array
title: Permissions
description: list of action keys that define what actions this resource role is permitted to do
attributes:
type: object
title: Attributes
description: optional dictionary of key-value pairs that can be used to store arbitrary metadata about this role. This metadata can be used to filter role using query parameters with attr_ prefix, currently supports only 'equals' operator
extends:
items:
type: string
type: array
title: Extends
description: 'list of role keys that define what roles this role extends. In other words: this role will automatically inherit all the permissions of the given roles in this list.'
granted_to:
allOf:
- $ref: '#/components/schemas/DerivedRoleBlockEdit'
title: Granted To
description: Derived role that inherit will be applied on this role
v1compat_settings:
type: object
title: V1Compat Settings
hidden_from_schema: true
v1compat_attributes:
type: object
title: V1Compat Attributes
hidden_from_schema: true
additionalProperties: false
type: object
title: RoleUpdate
example:
description: the editor role can read and write to documents
permissions:
- document:write
DerivedRoleBlockEdit:
properties:
when:
allOf:
- $ref: '#/components/schemas/permit_backend__schemas__schema_derived_role_rule__DerivationSettings'
title: When
description: the settings of the derived role
default:
no_direct_roles_on_object: false
users_with_role:
items:
$ref: '#/components/schemas/DerivedRoleRuleCreate'
type: array
title: Users With Role
description: the rules of the derived role
default: []
additionalProperties: false
type: object
title: DerivedRoleBlockEdit
example:
users_with_role:
- role: Admin
on_resource: organization
linked_by_relation: owner
RoleCreate:
properties:
key:
type: string
pattern: ^[A-Za-z0-9\-_]+$
title: Key
description: 'A URL-friendly name of the role (i.e: slug). You will be able to query later using this key instead of the id (UUID) of the role.'
name:
type: string
title: Name
description: The name of the role
description:
type: string
title: Description
description: optional description string explaining what this role represents, or what permissions are granted to it.
permissions:
items:
type: string
type: array
title: Permissions
description: list of action keys that define what actions this resource role is permitted to do
attributes:
type: object
title: Attributes
description: optional dictionary of key-value pairs that can be used to store arbitrary metadata about this role. This metadata can be used to filter role using query parameters with attr_ prefix, currently supports only 'equals' operator
extends:
items:
type: string
type: array
title: Extends
description: 'list of role keys that define what roles this role extends. In other words: this role will automatically inherit all the permissions of the given roles in this list.'
granted_to:
allOf:
- $ref: '#/components/schemas/DerivedRoleBlockEdit'
title: Granted To
description: Derived role that inherit will be applied on this role
v1compat_settings:
type: object
title: V1Compat Settings
hidden_from_schema: true
v1compat_attributes:
type: object
title: V1Compat Attributes
hidden_from_schema: true
v1compat_is_built_in:
type: boolean
title: V1Compat Is Built In
hidden_from_schema: true
additionalProperties: false
type: object
required:
- key
- name
title: RoleCreate
example:
key: editor
name: Editor
description: the editor role can read and write to documents
permissions:
- document:write
extends:
- viewer
PaginatedResult_RoleRead_:
properties:
data:
items:
$ref: '#/components/schemas/RoleRead'
type: array
title: Data
description: List of Roles
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[RoleRead]
RemoveRolePermissions:
properties:
permissions:
items:
type: string
type: array
title: Permissions
description: 'List of permissions to remove from the role. If a permission is not found it is skipped. Each permission can be either a resource action id, or `{resource_key}:{action_key}`,i.e: the "permission name".'
additionalProperties: false
type: object
required:
- permissions
title: RemoveRolePermissions
example:
permissions:
- document:share
RoleRead:
properties:
name:
type: string
title: Name
description: The name of the role
description:
type: string
title: Description
description: optional description string explaining what this role represents, or what permissions are granted to it.
permissions:
items:
type: string
type: array
title: Permissions
description: list of action keys that define what actions this resource role is permitted to do
attributes:
type: object
title: Attributes
description: optional dictionary of key-value pairs that can be used to store arbitrary metadata about this role. This metadata can be used to filter role using query parameters with attr_ prefix, currently supports only 'equals' operator
extends:
items:
type: string
type: array
title: Extends
description: 'list of role keys that define what roles this role extends. In other words: this role will automatically inherit all the permissions of the given roles in this list.'
granted_to:
allOf:
- $ref: '#/components/schemas/DerivedRoleBlockRead'
title: Granted To
description: "\n A derived role defintion block, typically contained whithin a role definition.\n The derived role is a role that is derived from the role definition.\n "
default: {}
v1compat_settings:
type: object
title: V1Compat Settings
hidden_from_schema: true
v1compat_attributes:
type: object
title: V1Compat Attributes
hidden_from_schema: true
key:
type: string
title: Key
description: 'A URL-friendly name of the role (i.e: slug). You will be able to query later using this key instead of the id (UUID) of the role.'
id:
type: string
format: uuid
title: Id
description: Unique id of the role
organization_id:
type: string
format: uuid
tit
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/permit-io/refs/heads/main/openapi/permit-io-roles-api-openapi.yml