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