openapi: 3.1.0
info:
title: Permit.io Access Requests (EAP) Access Requests (EAP) Users API
description: '
Authorization as a service
'
version: 2.0.0
tags:
- name: Users
description: '
Users represent human end-users of your applications that you''d like to enforce permissions on.
You must create a user object in Permit.io prior to trying to enforce permissions for that user.
A user is identified by its key, and you can only create one user with the same key inside a Permit environment.
You can place users within tenants via role assignments in order to enforce multi-tenancy in your app.
You may create users via the API (shown below), with one of the SDKs, or via the Permit cloud console.
'
paths:
/v2/facts/{proj_id}/{env_id}/users:
get:
tags:
- Users
summary: List Users
description: Lists all the users defined within an environment.
operationId: list_users
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: Text search for the user
required: false
schema:
type: string
title: Search
description: Text search for the user
name: search
in: query
- description: The search operator to use. `contains` performs a substring match on email, key, first_name, and last_name. `startswith` performs a prefix match on email, key, first_name, and last_name.
required: false
schema:
allOf:
- $ref: '#/components/schemas/SearchOperator'
description: The search operator to use. `contains` performs a substring match on email, key, first_name, and last_name. `startswith` performs a prefix match on email, key, first_name, and last_name.
default: contains
name: search_operator
in: query
- description: Match users with a specific role. To filter users without any roles, send an empty string.
required: false
schema:
type: string
title: Role
description: Match users with a specific role. To filter users without any roles, send an empty string.
name: role
in: query
- description: Should add resource instance roles
required: false
schema:
type: boolean
title: Include Resource Instance Roles
description: Should add resource instance roles
default: false
name: include_resource_instance_roles
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
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedResult_UserRead_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
post:
tags:
- Users
summary: Create User
description: 'Creates a new user inside the Permit.io system, from that point forward
you may run permission checks on that user.
Returns 201 if the user is created, 409 if the user already exists.
User is identified by its key, and you can only create one user with the same key inside a Permit environment.'
operationId: create_user
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/UserCreate'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UserRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/facts/{proj_id}/{env_id}/users/{user_id}:
get:
tags:
- Users
summary: Get User
description: Gets a user, if such user exists. Otherwise returns 404.
operationId: get_user
parameters:
- description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
required: true
schema:
type: string
title: User Id
description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
name: user_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/UserRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
put:
tags:
- Users
summary: Replace User
description: 'Replace User / Sync User upsert a user in the system.
If the user already exists, it will update the user with the new data.
If the user does not exist, it will create a new user with the provided data.
The user is identified by its key, and you can only create one user with the same key inside a Permit environment.
A 200 status code will be returned if the user already exists, and a 201 status code will be returned if the user is created.'
operationId: replace_user
parameters:
- description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
required: true
schema:
type: string
title: User Id
description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
name: user_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/UserCreate'
required: true
responses:
'200':
description: An existing user was replaced
content:
application/json:
schema:
$ref: '#/components/schemas/UserRead'
'201':
description: An new user was created
content:
application/json:
schema:
$ref: '#/components/schemas/UserRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
delete:
tags:
- Users
summary: Delete User
description: Deletes the user and all its related data.
operationId: delete_user
parameters:
- description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
required: true
schema:
type: string
title: User Id
description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
name: user_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:
- Users
summary: Update User
description: 'Partially updates the user definition.
Fields that will be provided will be completely overwritten.'
operationId: update_user
parameters:
- description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
required: true
schema:
type: string
title: User Id
description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
name: user_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/UserUpdate'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/UserRead'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/v2/facts/{proj_id}/{env_id}/users/{user_id}/roles:
post:
tags:
- Users
summary: Assign Role To User
description: 'Assigns a role to the user within the tenant.
The tenant defines the scope of the assignment. In other words, the role is effective only within the tenant.'
operationId: assign_role_to_user
parameters:
- description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
required: true
schema:
type: string
title: User Id
description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
name: user_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/UserRoleCreate'
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:
- Users
summary: Unassign Role From User
description: 'Unassigns the role from the user within the 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_from_user
parameters:
- description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
required: true
schema:
type: string
title: User Id
description: 'Either the unique id of the user, or the URL-friendly key of the user (i.e: the "slug").'
name: user_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: 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/UserRoleRemove'
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: []
components:
schemas:
UserInTenant:
properties:
tenant:
type: string
title: Tenant
description: The tenant key which the user is associated with
roles:
items:
type: string
type: array
title: Roles
description: List of roles assigned to the user in that tenant
status:
allOf:
- $ref: '#/components/schemas/UserStatus'
description: Whether the user has signed in or not
resource_instance_roles:
items:
$ref: '#/components/schemas/UserResourceInstanceRole'
type: array
title: Resource Instance Roles
default: []
additionalProperties: false
type: object
required:
- tenant
- roles
- status
title: UserInTenant
UserStatus:
type: string
enum:
- active
- pending
title: UserStatus
description: An enumeration.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
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'
UserRoleRemove:
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)
additionalProperties: false
type: object
required:
- role
- tenant
title: UserRoleRemove
example:
role: editor
tenant: google-inc
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
UserRole:
properties:
role:
type: string
title: Role
description: the role that is assigned
tenant:
type: string
title: Tenant
description: the tenant the role is associated with
additionalProperties: false
type: object
required:
- role
- tenant
title: UserRole
UserRead:
properties:
key:
type: string
title: Key
description: A unique id by which Permit will identify the user for permission checks.
id:
type: string
format: uuid
title: Id
description: Unique id of the user
organization_id:
type: string
format: uuid
title: Organization Id
description: Unique id of the organization that the user belongs to.
project_id:
type: string
format: uuid
title: Project Id
description: Unique id of the project that the user belongs to.
environment_id:
type: string
format: uuid
title: Environment Id
description: Unique id of the environment that the user belongs to.
associated_tenants:
items:
$ref: '#/components/schemas/UserInTenant'
type: array
title: Associated Tenants
default: []
roles:
items:
$ref: '#/components/schemas/UserRole'
type: array
title: Roles
default: []
deprecated: true
created_at:
type: string
format: date-time
title: Created At
description: Date and time when the user was created (ISO_8601 format).
updated_at:
type: string
format: date-time
title: Updated At
description: Date and time when the user was last updated/modified (ISO_8601 format).
email:
type: string
format: email
title: Email
description: The email of the user. If synced, will be unique inside the environment.
first_name:
type: string
title: First Name
description: First name of the user.
last_name:
type: string
title: Last Name
description: Last name of the user.
attributes:
type: object
title: Attributes
description: Arbitrary user attributes that will be used to enforce attribute-based access control policies.
default: {}
additionalProperties: false
type: object
required:
- key
- id
- organization_id
- project_id
- environment_id
- created_at
- updated_at
title: UserRead
example:
id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
organization_id: 7c60d51f-b44e-4682-87d6-449835ea4de6
project_id: 405d8375-3514-403b-8c43-83ae74cfe0e9
environment_id: 40ef0e48-a11f-4963-a229-e396c9f7e7c4
key: user|892179821739812389327
email: jane@coolcompany.com
created_at: '2019-08-24T14:15:22Z'
updated_at: '2019-08-24T14:15:22Z'
first_name: Jane
last_name: Doe
attributes:
department: marketing
age: 30
subscription:
tier: pro
expired: false
associated_tenants:
- tenant: stripe-inc
roles:
- admin
status: active
- tenant: othercompany.com
roles:
- viewer
status: pending
roles:
- role: admin
tenant: stripe-inc
- role: viewer
tenant: othercompany.com
UserUpdate:
properties:
email:
type: string
format: email
title: Email
description: The email of the user. If synced, will be unique inside the environment.
first_name:
type: string
title: First Name
description: First name of the user.
last_name:
type: string
title: Last Name
description: Last name of the user.
attributes:
type: object
title: Attributes
description: Arbitrary user attributes that will be used to enforce attribute-based access control policies.
default: {}
additionalProperties: false
type: object
title: UserUpdate
UserCreate:
properties:
key:
type: string
pattern: ^[A-Za-z0-9|@+\-\._]+$
title: Key
description: A unique id by which Permit will identify the user for permission checks.
email:
type: string
format: email
title: Email
description: The email of the user. If synced, will be unique inside the environment.
first_name:
type: string
title: First Name
description: First name of the user.
last_name:
type: string
title: Last Name
description: Last name of the user.
attributes:
type: object
title: Attributes
description: Arbitrary user attributes that will be used to enforce attribute-based access control policies.
default: {}
role_assignments:
items:
$ref: '#/components/schemas/UserRoleCreate'
type: array
title: Role Assignments
description: List of roles to assign to the user in the environment.
additionalProperties: false
type: object
required:
- key
title: UserCreate
example:
key: user|892179821739812389327
email: jane@coolcompany.com
first_name: Jane
last_name: Doe
attributes:
department: marketing
age: 30
subscription:
tier: pro
expired: false
role_assignments:
- role: admin
tenant: stripe-inc
- role: viewer
tenant: othercompany.com
SearchOperator:
type: string
enum:
- startswith
- endswith
- contains
title: SearchOperator
description: An enumeration.
PaginatedResult_UserRead_:
properties:
data:
items:
$ref: '#/components/schemas/UserRead'
type: array
title: Data
description: List of Users
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[UserRead]
UserRoleCreate:
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.
additionalProperties: false
type: object
required:
- role
title: UserRoleCreate
example:
role: admin
tenant: stripe-inc
UserResourceInstanceRole:
properties:
resource_instance:
type: string
title: Resource Instance
description: The resource instance key which the role is associated with
resource:
type: string
title: Resource
description: The resource type which the role is associated with
role:
type: string
title: Role
description: The role key of this resource role
additionalProperties: false
type: object
required:
- resource_instance
- resource
- role
title: UserResourceInstanceRole
securitySchemes:
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/permit-io/refs/heads/main/openapi/permit-io-users-api-openapi.yml