openapi: 3.1.0
info:
title: Permit.io Access Requests (EAP) Access Requests (EAP) Resources API
description: '
Authorization as a service
'
version: 2.0.0
tags:
- name: Resources
description: '
Resources are *types* of objects or feature names that you wish to protect (or gate) with permissions.
For example, if you build a document-sharing app like google docs, you might want to define a "document" resource.
A resource definition block typically contains **actions**.
Actions are the various ways you can interact with the object / feature. Each (resource, action) pair defines a unique permission level.
A resource may also contain:
- roles (if you wish to define resource-bound roles or if your permissions model is relational)
- relations to other resources (if your permissions model is relational, i.e: you work with a ReBAC model)
- attributes (attributes that are typically defined on the resource, typically used in ABAC models)
'
paths:
/v2/schema/{proj_id}/{env_id}/resources:
get:
tags:
- Resources
summary: List Resources
description: Lists all the resources defined in your schema.
operationId: list_resources
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 include or exclude built-in resources, default is False
required: false
schema:
type: boolean
title: Include Built In
description: Whether to include or exclude built-in resources, default is False
default: false
name: include_built_in
in: query
- 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_ResourceRead_'
- items:
$ref: '#/components/schemas/ResourceRead'
type: array
title: Response List Resources V2 Schema Proj Id Env Id Resources Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
post:
tags:
- Resources
summary: Create Resource
description: Creates a new resource (a type of object you may protect with permissions).
operationId: create_resource
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/ResourceCreate'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/schema/{proj_id}/{env_id}/resources/{resource_id}:
get:
tags:
- Resources
summary: Get Resource
description: Gets a single resource, if such resource exists.
operationId: get_resource
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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
put:
tags:
- Resources
summary: Replace Resource
description: 'Replaces the resource definition, or creates it if it doesn''t exist.
- If some actions are removed or renamed from the resource definition,
role and permissions assignments for these actions will be revoked.'
operationId: replace_resource
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/ResourceReplace'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
delete:
tags:
- Resources
summary: Delete Resource
description: Deletes the resource and all its related data.
operationId: delete_resource
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
responses:
'204':
description: Successful Response
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
patch:
tags:
- Resources
summary: Update Resource
description: 'Partially updates the resource definition.
Fields that will be provided will be completely overwritten.'
operationId: update_resource
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/ResourceUpdate'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
ResourceUpdate:
properties:
name:
type: string
title: Name
description: The name of the resource
urn:
type: string
title: Urn
description: The [URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name) (Uniform Resource Name) of the resource
description:
type: string
title: Description
description: An optional longer description of what this resource respresents in your system
actions:
additionalProperties:
$ref: '#/components/schemas/ActionBlockEditable'
type: object
title: Actions
description: "\n A actions definition block, typically contained within a resource type definition block.\n The actions represents the ways you can interact with a protected resource.\n "
type_attributes:
type: object
title: Type Attributes
description: optional dictionary of key-value pairs that can be used to store arbitrary metadata about this resource. This metadata can be used to filter resource using query parameters with attr_ prefix
attributes:
additionalProperties:
$ref: '#/components/schemas/AttributeBlockEditable'
type: object
title: Attributes
description: Attributes that each resource of this type defines, and can be used in your ABAC policies.
roles:
patternProperties:
^[A-Za-z0-9\-_]+$:
$ref: '#/components/schemas/RoleBlockEditable'
additionalProperties:
$ref: '#/components/schemas/RoleBlockEditable'
type: object
title: Roles
description: Roles defined on this resource. The key is the role name, and the value contains the role properties such as granted permissions, base roles, etc.
relations:
patternProperties:
^[A-Za-z0-9\-_]+$:
type: string
pattern: ^[A-Za-z0-9\-_]+$
additionalProperties:
type: string
pattern: ^[A-Za-z0-9\-_]+$
type: object
title: Relations
description: Relations to other resources. The key is the relation key, and the value is the related resource.
v1compat_path:
type: string
title: V1Compat Path
hidden_from_schema: true
v1compat_type:
type: string
title: V1Compat Type
hidden_from_schema: true
v1compat_name:
type: string
title: V1Compat Name
hidden_from_schema: true
additionalProperties: false
type: object
title: ResourceUpdate
AttributeBlockEditable:
properties:
type:
allOf:
- $ref: '#/components/schemas/AttributeType'
description: 'The type of the attribute, we currently support: `bool`, `number` (ints, floats), `time` (a timestamp), `string`, and `json`.'
description:
type: string
title: Description
description: optional description string explaining what data this attribute will store
additionalProperties: false
type: object
required:
- type
title: AttributeBlockEditable
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
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
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
AttributeType:
type: string
enum:
- bool
- number
- string
- time
- array
- json
- object
- object_array
title: AttributeType
description: supported attribute primitives
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
ResourceReplace:
properties:
name:
type: string
title: Name
description: The name of the resource
urn:
type: string
title: Urn
description: The [URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name) (Uniform Resource Name) of the resource
description:
type: string
title: Description
description: An optional longer description of what this resource respresents in your system
actions:
additionalProperties:
$ref: '#/components/schemas/ActionBlockEditable'
type: object
title: Actions
description: "\n A actions definition block, typically contained within a resource type definition block.\n The actions represents the ways you can interact with a protected resource.\n "
type_attributes:
type: object
title: Type Attributes
description: optional dictionary of key-value pairs that can be used to store arbitrary metadata about this resource. This metadata can be used to filter resource using query parameters with attr_ prefix
attributes:
additionalProperties:
$ref: '#/components/schemas/AttributeBlockEditable'
type: object
title: Attributes
description: Attributes that each resource of this type defines, and can be used in your ABAC policies.
roles:
patternProperties:
^[A-Za-z0-9\-_]+$:
$ref: '#/components/schemas/RoleBlockEditable'
additionalProperties:
$ref: '#/components/schemas/RoleBlockEditable'
type: object
title: Roles
description: Roles defined on this resource. The key is the role name, and the value contains the role properties such as granted permissions, base roles, etc.
relations:
patternProperties:
^[A-Za-z0-9\-_]+$:
type: string
pattern: ^[A-Za-z0-9\-_]+$
additionalProperties:
type: string
pattern: ^[A-Za-z0-9\-_]+$
type: object
title: Relations
description: Relations to other resources. The key is the relation key, and the value is the related resource.
v1compat_path:
type: string
title: V1Compat Path
hidden_from_schema: true
v1compat_type:
type: string
title: V1Compat Type
hidden_from_schema: true
v1compat_name:
type: string
title: V1Compat Name
hidden_from_schema: true
additionalProperties: false
type: object
required:
- name
- actions
title: ResourceReplace
RoleBlockEditable:
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
required:
- name
title: RoleBlockEditable
ActionBlockEditable:
properties:
name:
type: string
title: Name
description: a more descriptive name for the action
description:
type: string
title: Description
description: optional description string explaining what this action represents in your system
attributes:
type: object
title: Attributes
v1compat_path:
type: string
title: V1Compat Path
hidden_from_schema: true
v1compat_name:
type: string
title: V1Compat Name
hidden_from_schema: true
additionalProperties: false
type: object
title: ActionBlockEditable
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
RelationBlockRead:
properties:
description:
type: string
title: Description
description: An optional longer description of what this relation represents in your system
resource_id:
type: string
format: uuid
title: Resource Id
description: Unique id of the relation
relation_name:
type: string
title: Relation Name
description: a more descriptive name for the relation
hidden_from_schema: true
resource:
type: string
title: Resource
description: The resource key
additionalProperties: false
type: object
required:
- resource_id
- resource
title: RelationBlockRead
example:
resource_id: 3cb94048-6459-49c0-a895-a8202de7390c
relation_name: parent
resource: parent-resource
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
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
description: Unique id of the environment that the role belongs to.
resource_id:
type: string
format: uuid
title: Resource Id
description: Unique id of the resource that the role belongs to.
resource:
type: string
title: Resource
description: The unique resource key that the role belongs to.
created_at:
type: string
format: date-time
title: Created At
description: Date and time when the role was created (ISO_8601 format).
updated_at:
type: string
format: date-time
title: Updated At
description: Date and time when the role was last updated/modified (ISO_8601 format).
additionalProperties: false
type: object
required:
- name
- key
- id
- organization_id
- project_id
- environment_id
-
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/permit-io/refs/heads/main/openapi/permit-io-resources-api-openapi.yml