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:
    HTTPBearer:
      type: http
      description: 'Authorization header, we support the bearer authentication scheme (see: RFC 6750)'
      scheme: bearer
      bearerFormat: JWT