Channex Property Users API

openapi: 3.2.0
info:
  title: Channex.io — Public Property Users API
  version: 0.0.0
  description: Manage Property Users — a user's access to a single Property. An access carries a role and, optionally, access policy overrides on top of it, and ownership can be handed to another user.
servers:
- url: https://app.channex.io/api/v1
  description: Production server
  variables: {}
- url: https://staging.channex.io/api/v1
  description: Staging server
  variables: {}
security:
- UserApiKeyAuth: []
tags:
- name: Property Users
  description: Manage Property Users — a user's access to a single Property. An access carries a role and, optionally, access policy overrides on top of it, and ownership can be handed to another user.
paths:
  /property_users:
    get:
      operationId: PropertyUsers_list
      summary: List property users
      description: List the users of one property. `filter[property_id]` is required. Not paginated.
      parameters:
      - $ref: '#/components/parameters/PropertyUsers.PropertyUserListParams'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PropertyUsers.PropertyUserResource'
                description: A plain data-array envelope without pagination — used by reference/dictionary endpoints.
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.Unauthorized'
        '422':
          description: The request has missing or invalid arguments; `details` lists the messages per argument.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.InvalidArguments'
      tags:
      - Property Users
    post:
      operationId: PropertyUsers_invite
      summary: Invite a user to a property
      description: 'Invite a user to a property. A user without a Channex account gets one, and an

        onboarding email. An address already invited to the property is refused. The

        created access is returned with `201 Created`.'
      parameters: []
      responses:
        '201':
          description: 201 Created response wrapping a resource body.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/PropertyUsers.PropertyUserResource'
                description: JSON:API document wrapping a single resource.
        '400':
          description: The request body could not be parsed as JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.UnparsableRequest'
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.Unauthorized'
        '403':
          description: The authenticated user lacks permission to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.Forbidden'
        '422':
          description: The request has missing or invalid arguments; `details` lists the messages per argument.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/Common.Errors.InvalidArguments'
                - $ref: '#/components/schemas/Common.Errors.ValidationError'
      tags:
      - Property Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PropertyUsers.PropertyUserCreateRequest'
  /property_users/{id}:
    get:
      operationId: PropertyUsers_read
      summary: Retrieve a property user
      description: Retrieve an access by its identifier.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Common.Scalars.id'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/PropertyUsers.PropertyUserResource'
                description: JSON:API document wrapping a single resource.
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.Unauthorized'
        '403':
          description: The authenticated user lacks permission to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.Forbidden'
        '404':
          description: The requested resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.NotFound'
        '422':
          description: The request has missing or invalid arguments; `details` lists the messages per argument.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.InvalidArguments'
      tags:
      - Property Users
    put:
      operationId: PropertyUsers_update
      summary: Update a property user
      description: 'Update an access: its role, its access policy overrides, or the property and user it

        links. Attributes absent from the request are left unchanged. The updated access is

        returned.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Common.Scalars.id'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                properties:
                  data:
                    $ref: '#/components/schemas/PropertyUsers.PropertyUserResource'
                description: JSON:API document wrapping a single resource.
        '400':
          description: The request body could not be parsed as JSON.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.UnparsableRequest'
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.Unauthorized'
        '403':
          description: The authenticated user lacks permission to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.Forbidden'
        '404':
          description: The requested resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.NotFound'
        '422':
          description: The request has missing or invalid arguments; `details` lists the messages per argument.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/Common.Errors.InvalidArguments'
                - $ref: '#/components/schemas/Common.Errors.ValidationError'
      tags:
      - Property Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PropertyUsers.PropertyUserUpdateRequest'
    delete:
      operationId: PropertyUsers_withdraw
      summary: Withdraw a property user
      description: 'Withdraw a user''s access to the property. A user cannot withdraw their own access:

        the request is refused with `400` and `details` naming the reason.'
      parameters:
      - name: id
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Common.Scalars.id'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.JsonApi.SuccessMessage'
        '400':
          description: The request could not be processed in the current state; `details` explains why.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.BadRequestWithReason'
        '401':
          description: Authentication credentials are missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.Unauthorized'
        '403':
          description: The authenticated user lacks permission to perform this action.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.Forbidden'
        '404':
          description: The requested resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.NotFound'
        '422':
          description: The request has missing or invalid arguments; `details` lists the messages per argument.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Common.Errors.InvalidArguments'
      tags:
      - Property Users
components:
  schemas:
    Common.Errors.ValidationError:
      type: object
      required:
      - errors
      properties:
        errors:
          $ref: '#/components/schemas/Common.Errors.ValidationErrorObject'
      description: The request body failed validation.
    Common.Errors.UnparsableRequest:
      type: object
      required:
      - errors
      properties:
        errors:
          $ref: '#/components/schemas/Common.Errors.UnparsableRequestObject'
      description: The request body could not be parsed as JSON.
    Authentication.EmbeddedUser:
      type: object
      required:
      - type
      - id
      - attributes
      properties:
        type:
          type: string
          enum:
          - user
        id:
          $ref: '#/components/schemas/Common.Scalars.id'
        attributes:
          $ref: '#/components/schemas/Authentication.EmbeddedUserAttributes'
      description: A user embedded in another resource's relationships, carrying identifier, name and email.
    PropertyUsers.PropertyUserResource:
      type: object
      required:
      - type
      - id
      - attributes
      - relationships
      properties:
        type:
          type: string
          enum:
          - property_user
        id:
          $ref: '#/components/schemas/Common.Scalars.id'
        attributes:
          $ref: '#/components/schemas/PropertyUsers.PropertyUser'
        relationships:
          $ref: '#/components/schemas/PropertyUsers.PropertyUserRelationships'
      description: 'A property user resource: the access attributes plus the property and user it links.'
    PropertyUsers.PropertyUserCreateRequest:
      type: object
      required:
      - invite
      properties:
        invite:
          $ref: '#/components/schemas/PropertyUsers.PropertyUserCreate'
      description: Request body accepted when inviting a user to a property.
    PropertyUsers.PropertyUserCreate:
      type: object
      required:
      - property_id
      - role
      - user_email
      properties:
        property_id:
          allOf:
          - $ref: '#/components/schemas/Common.Scalars.id'
          description: UUID of the property the access is granted to.
          examples:
          - 52397a6e-c330-44f4-a293-47042d3a3607
        role:
          $ref: '#/components/schemas/PropertyUsers.PropertyUserRole'
        overrides:
          anyOf:
          - type: object
            unevaluatedProperties: {}
          - type: 'null'
          description: Access policy overrides applied to this access on top of the role, or null when the role applies unchanged.
        user_email:
          allOf:
          - $ref: '#/components/schemas/Common.Scalars.email'
          description: 'Email address of the user to invite. A user without a Channex account gets one,

            and an onboarding email.'
          examples:
          - other_user@channex.io
      description: Attributes accepted when inviting a user to a property.
    Common.Errors.InvalidArgumentsObject:
      type: object
      required:
      - code
      - title
      - details
      properties:
        code:
          type: string
          enum:
          - bad_request
        title:
          type: string
          enum:
          - Bad Request
        details:
          type: object
          unevaluatedProperties:
            type: array
            items:
              type: string
          description: Maps each invalid argument to the list of validation messages for that argument.
          examples:
          - id:
            - can't be blank
      description: Error object for invalid request arguments, adding per-argument messages.
    PropertyUsers.PropertyUserUpdateRequest:
      type: object
      required:
      - property_user
      properties:
        property_user:
          $ref: '#/components/schemas/PropertyUsers.PropertyUserUpdate'
      description: Request body accepted when updating a property user.
    Authentication.EmbeddedUserAttributes:
      type: object
      required:
      - id
      - name
      - email
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/Common.Scalars.id'
          description: User identifier. Mirrors the resource id.
        name:
          type: string
          description: Display name of the user.
          examples:
          - Channex User
        email:
          allOf:
          - $ref: '#/components/schemas/Common.Scalars.email'
          description: Email address the account is registered with.
          examples:
          - user@channex.io
      description: Identifier, display name and email address of an embedded user.
    Common.Errors.NotFound:
      type: object
      required:
      - errors
      properties:
        errors:
          type: object
          required:
          - code
          - title
          properties:
            code:
              type: string
              enum:
              - resource_not_found
            title:
              type: string
              enum:
              - Resource Not Found
          description: 'Shape of a single JSON:API error object: a stable machine code plus a human-readable title.'
      description: The requested resource does not exist.
    Common.Scalars.email:
      type: string
      format: email
    Common.Errors.BadRequestReasonObject:
      type: object
      required:
      - code
      - title
      - details
      properties:
        code:
          type: string
          enum:
          - bad_request
        title:
          type: string
          enum:
          - Bad Request
        details:
          type: string
          description: Human-readable reason the request could not be processed.
          examples:
          - User already invited
      description: Error object for a bad request, adding a single human-readable reason.
    PropertyUsers.EmbeddedPropertyRef:
      type: object
      required:
      - id
      - type
      properties:
        id:
          $ref: '#/components/schemas/Common.Scalars.id'
        type:
          type: string
          enum:
          - property
      description: The property an access belongs to, as it appears among a property user's relationships.
    Common.Errors.UnparsableRequestObject:
      type: object
      required:
      - code
      - title
      - details
      properties:
        code:
          type: string
          enum:
          - bad_request
        title:
          type: string
          enum:
          - Bad Request
        details:
          type: object
          unevaluatedProperties:
            type: string
          description: Maps the part of the request that could not be parsed to the reason.
          examples:
          - body: malformed JSON
      description: Error object for an unparsable request body, naming the malformed part.
    PropertyUsers.PropertyUserRelationships:
      type: object
      required:
      - property
      - user
      properties:
        property:
          type: object
          properties:
            data:
              $ref: '#/components/schemas/PropertyUsers.EmbeddedPropertyRef'
          required:
          - data
          description: The property the access is granted to.
        user:
          type: object
          properties:
            data:
              $ref: '#/components/schemas/Authentication.EmbeddedUser'
          required:
          - data
          description: The user the access is granted to.
      description: 'Relationships of a property user resource: the property the access is for and the user it is granted to.'
    PropertyUsers.PropertyUser:
      type: object
      required:
      - id
      - user_id
      - property_id
      - role
      - overrides
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/Common.Scalars.id'
          description: Unique property user identifier. Mirrors the top-level resource `id`.
          examples:
          - 776533f2-c10e-49d8-bddc-14b3e27c2a00
        user_id:
          allOf:
          - $ref: '#/components/schemas/Common.Scalars.id'
          description: UUID of the user the access is granted to.
          examples:
          - c9cfa184-5095-4ef2-bbe2-e723ffb49184
        property_id:
          allOf:
          - $ref: '#/components/schemas/Common.Scalars.id'
          description: UUID of the property the access is granted to.
          examples:
          - 52397a6e-c330-44f4-a293-47042d3a3607
        role:
          $ref: '#/components/schemas/PropertyUsers.PropertyUserRole'
        overrides:
          anyOf:
          - type: object
            unevaluatedProperties: {}
          - type: 'null'
          description: Access policy overrides applied to this access on top of the role, or null when the role applies unchanged.
      description: 'A user''s access to a property, as returned in responses: every attribute is present.'
    Common.Scalars.id:
      type: string
      format: uuid
      examples:
      - 716305c4-561a-4561-a187-7f5b8aeb5920
    Common.Errors.ValidationErrorObject:
      type: object
      required:
      - code
      - title
      - details
      properties:
        code:
          type: string
          enum:
          - validation_error
        title:
          type: string
          enum:
          - Validation Error
        details:
          type: object
          unevaluatedProperties:
            type: array
            items:
              type: string
          description: Maps each invalid field to the list of validation messages for that field.
          examples:
          - field_name:
            - can't be blank
      description: Error object for a failed validation, adding per-field messages.
    Common.JsonApi.SuccessMessage:
      type: object
      required:
      - meta
      properties:
        meta:
          type: object
          properties:
            message:
              type: string
              examples:
              - Success
          required:
          - message
      description: Success response carrying only a meta message (no resource body).
    Common.Errors.Unauthorized:
      type: object
      required:
      - errors
      properties:
        errors:
          type: object
          required:
          - code
          - title
          properties:
            code:
              type: string
              enum:
              - unauthorized
            title:
              type: string
              enum:
              - Unauthorized
          description: 'Shape of a single JSON:API error object: a stable machine code plus a human-readable title.'
      description: Authentication credentials are missing or invalid.
    Common.Errors.InvalidArguments:
      type: object
      required:
      - errors
      properties:
        errors:
          $ref: '#/components/schemas/Common.Errors.InvalidArgumentsObject'
      description: The request has missing or invalid arguments; `details` lists the messages per argument.
    Common.Errors.Forbidden:
      type: object
      required:
      - errors
      properties:
        errors:
          type: object
          required:
          - code
          - title
          properties:
            code:
              type: string
              enum:
              - forbidden
            title:
              type: string
              enum:
              - Forbidden
          description: 'Shape of a single JSON:API error object: a stable machine code plus a human-readable title.'
      description: The authenticated user lacks permission to perform this action.
    PropertyUsers.PropertyUserRole:
      type: string
      enum:
      - owner
      - user
      description: Role granted to a user for a property.
    Common.Errors.BadRequestWithReason:
      type: object
      required:
      - errors
      properties:
        errors:
          $ref: '#/components/schemas/Common.Errors.BadRequestReasonObject'
      description: The request could not be processed in the current state; `details` explains why.
    PropertyUsers.PropertyUserUpdate:
      type: object
      properties:
        property_id:
          allOf:
          - $ref: '#/components/schemas/Common.Scalars.id'
          description: UUID of the property the access is granted to.
          examples:
          - 52397a6e-c330-44f4-a293-47042d3a3607
        role:
          $ref: '#/components/schemas/PropertyUsers.PropertyUserRole'
        overrides:
          anyOf:
          - type: object
            unevaluatedProperties: {}
          - type: 'null'
          description: Access policy overrides applied to this access on top of the role, or null when the role applies unchanged.
        user_id:
          allOf:
          - $ref: '#/components/schemas/Common.Scalars.id'
          description: UUID of the user to grant the access to.
          examples:
          - c9cfa184-5095-4ef2-bbe2-e723ffb49184
      description: Attributes accepted when updating a property user. Every attribute is optional; attributes absent from the request are left unchanged.
  parameters:
    PropertyUsers.PropertyUserListParams:
      name: filter[property_id]
      in: query
      required: true
      description: UUID of the property whose users to list.
      schema:
        $ref: '#/components/schemas/Common.Scalars.id'
      explode: false
  securitySchemes:
    UserApiKeyAuth:
      type: apiKey
      in: header
      name: user-api-key
      description: API key for programmatic access, sent in the `user-api-key` header.
x-provenance:
  method: harvested
  publisher: Channex
  source: https://openapi.channex.io/public/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)