Roles allow you to associate permissions indirectly via a job function. Resource roles allow you to grant roles that are scoped to a resource, thus expressing ownership or arbitrary relationships between an actor (i.e: user) and a specific object. This API allows you to manipulate roles: assign or unassign permissions to a role, define hierarchy (inheritance) between two roles or define relationships between two roles.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/permit-io-resource-roles-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
openapi: 3.1.0
info:
title: Permit.io Access Requests (EAP) Access Requests (EAP) Resource Roles API
description: '
Authorization as a service
'
version: 2.0.0
tags:
- name: Resource Roles
description: '
Roles allow you to associate permissions indirectly via a job function.
Resource roles allow you to grant roles that are scoped to a resource, thus
expressing ownership or arbitrary relationships between an actor (i.e: user) and
a specific object.
This API allows you to manipulate roles: assign or unassign permissions to a role,
define hierarchy (inheritance) between two roles or define relationships between two roles.
'
paths:
/v2/schema/{proj_id}/{env_id}/resources/{resource_id}/roles:
get:
tags:
- Resource Roles
summary: List Resource Roles
description: Lists all the roles defined on the resource.
operationId: list_resource_roles
parameters:
- description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
required: true
schema:
type: string
title: Resource Id
description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
example: my_resource
name: resource_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
- 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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ResourceRoleRead'
type: array
title: Response List Resource Roles V2 Schema Proj Id Env Id Resources Resource Id Roles Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
post:
tags:
- Resource Roles
summary: Create Resource Role
description: Creates a new role associated with the resource.
operationId: create_resource_role
parameters:
- description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
required: true
schema:
type: string
title: Resource Id
description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
example: my_resource
name: resource_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/ResourceRoleCreate'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceRoleRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/schema/{proj_id}/{env_id}/resources/{resource_id}/roles/{role_id}:
get:
tags:
- Resource Roles
summary: Get Resource Role
description: Gets a single role defined on the resource, if such role exists.
operationId: get_resource_role
parameters:
- description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
required: true
schema:
type: string
title: Resource Id
description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
example: my_resource
name: resource_id
in: path
- 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/ResourceRoleRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
delete:
tags:
- Resource Roles
summary: Delete Resource Role
description: 'Deletes the role and all its related data.
This includes any permissions granted to said role.'
operationId: delete_resource_role
parameters:
- description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
required: true
schema:
type: string
title: Resource Id
description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
example: my_resource
name: resource_id
in: path
- 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:
- Resource Roles
summary: Update Resource Role
description: 'Partially updates the role defined on a resource.
Fields that will be provided will be completely overwritten.'
operationId: update_resource_role
parameters:
- description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
required: true
schema:
type: string
title: Resource Id
description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
example: my_resource
name: resource_id
in: path
- 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/ResourceRoleUpdate'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceRoleRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/schema/{proj_id}/{env_id}/resources/{resource_id}/roles/{role_id}/permissions:
post:
tags:
- Resource 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_resource_role
parameters:
- description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
required: true
schema:
type: string
title: Resource Id
description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
example: my_resource
name: resource_id
in: path
- 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/ResourceRoleRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
delete:
tags:
- Resource 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_resource_role
parameters:
- description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
required: true
schema:
type: string
title: Resource Id
description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
example: my_resource
name: resource_id
in: path
- 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/ResourceRoleRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/schema/{proj_id}/{env_id}/resources/{resource_id}/roles/{role_id}/ancestors:
get:
tags:
- Resource Roles
summary: Get Resource Role Ancestors
operationId: get_resource_role_ancestors
parameters:
- description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
required: true
schema:
type: string
title: Resource Id
description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
example: my_resource
name: resource_id
in: path
- 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/ResourceRoleList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/schema/{proj_id}/{env_id}/resources/{resource_id}/roles/{role_id}/descendants:
get:
tags:
- Resource Roles
summary: Get Resource Role Descendants
operationId: get_resource_role_descendants
parameters:
- description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
required: true
schema:
type: string
title: Resource Id
description: 'Either the unique id of the resource, or the URL-friendly key of the resource (i.e: the "slug").'
example: my_resource
name: resource_id
in: path
- 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/ResourceRoleList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
ResourceRoleUpdate:
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.'
default: []
granted_to:
allOf:
- $ref: '#/components/schemas/DerivedRoleBlockEdit'
title: Granted To
description: Derived role that inherit will be applied on this role
additionalProperties: false
type: object
title: ResourceRoleUpdate
example:
description: the maintainer role can read from the repo and push changes
permissions:
- push
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
ResourceRoleList:
properties:
roles:
anyOf:
- items:
$ref: '#/components/schemas/ResourceRoleRead'
type: array
- $ref: '#/components/schemas/PaginatedResult_ResourceRoleRead_'
title: Roles
additionalProperties: false
type: object
required:
- roles
title: ResourceRoleList
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
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
ResourceRoleRead:
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.'
default: []
granted_to:
allOf:
- $ref: '#/components/schemas/DerivedRoleBlockRead'
title: Granted To
description: Derived role that inherit will be applied on this role
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
title: Organization Id
description: Unique id of the organization that the role belongs to.
project_id:
type: string
format: uuid
title: Project Id
description: Unique id of the project that the role belongs to.
environment_id:
type: string
format: uuid
title: Environment Id
descri
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/permit-io/refs/heads/main/openapi/permit-io-resource-roles-api-openapi.yml