permissions.yaml

openapi: 3.0.3

info:
  title: Permissions API
  version: 1.0.0
  description: Flexible Role-based Access Control for epilot
tags:
  - name: Roles
    description: Manage roles and grants
  - name: Assignments
    description: Assign roles to users
security:
  - EpilotAuth: []
  - EpilotOrg: []

servers:
  - url: https://permissions.sls.epilot.io

paths:
  "/v1/permissions/me":
    get:
      operationId: listCurrentRoles
      summary: listCurrentRoles
      description: Returns roles and grants assigned to current user
      tags:
        - Roles
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items:
                      $ref: "#/components/schemas/Role"
  "/v1/permissions/roles":
    get:
      operationId: listAllRoles
      summary: listAllRoles
      description: Returns list of all roles in organization
      tags:
        - Roles
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items:
                      $ref: "#/components/schemas/Role"
    post:
      operationId: createRole
      summary: createRole
      description: Create role
      tags:
        - Roles
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRolePayload"
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
  "/v1/permissions/roles:search":
    post:
      operationId: searchRoles
      summary: searchRoles
      description: Search Roles
      tags:
        - Roles
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RoleSearchInput"
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  hits:
                    type: number
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/Role"
  "/v1/permissions/roles/{roleId}":
    get:
      operationId: getRole
      summary: getRole
      description: Get role by id
      tags:
        - Roles
      parameters:
        - name: roleId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RoleId"
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
    put:
      operationId: putRole
      summary: putRole
      description: Create or update role
      tags:
        - Roles
      parameters:
        - name: roleId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RoleId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RolePayload"
            x-examples:
              "User role: manager":
                description: Example manager role
                value:
                  id: "123:manager"
                  name: Manager
                  slug: manager
                  type: user_role
                  organization_id: "123"
                  grants:
                    - action: "entity:view"
                      resource: "*"
                    - action: "entity:update"
                      resource: "*"
                    - action: "user:view"
                    - action: "user:invite"
                    - action: "role:view"
                    - action: "role:create"
                    - action: "role:assign"
                    - action: "entity:view"
                      resource: "file:*"
                      conditions:
                        - attribute: "_tags"
                          operation: "equals"
                          values:
                            - offer
                            - contract
                    - action: "message:view"
                      dependencies:
                        - action: "entity:view"
                          resource: "message*"
                        - action: "entity:view"
                          resource: "thread*"
                    - action: "message:send"
                      dependencies:
                        - action: "entity:*"
                          resource: "message*"
                        - action: "entity:*"
                          resource: "thread*"
                    - action: "workflow:*"
              "User role: employee":
                description: Example employee role
                value:
                  id: "123:employee"
                  name: Employee
                  slug: employee
                  type: user_role
                  organization_id: "123"
                  grants:
                    - action: "entity:view"
                      resource: "*"
                    - action: "entity:update"
                      resource: "*"
                    - action: "user:view"
                    - action: "message:view"
                      dependencies:
                        - action: "entity:view"
                          resource: "message*"
                        - action: "entity:view"
                          resource: "thread*"
                    - action: "message:send"
                      dependencies:
                        - action: "entity:*"
                          resource: "message*"
                        - action: "entity:*"
                          resource: "thread*"
                    - action: "workflow:execution:*"
              "User role: administrator":
                description: Example administrator role
                value:
                  id: "123:administrator"
                  name: Administrator
                  slug: administrator
                  type: user_role
                  organization_id: "123"
                  grants:
                    - action: "*"
                      resource: "*"
              "Organization root role":
                description: Example organization root role. Must be satisifed for all org queries.
                value:
                  id: "123:root"
                  name: Organization root role
                  slug: root
                  type: org_role
                  organization_id: "123"
                  grants:
                    - action: "*"
                      resource: "*"
                    - action: "webhook:*"
                      effect: deny
              "Share role":
                description: Example share role. This can be assigned to users in other organizations
                value:
                  id: "123:example_share_role"
                  name: Example opportunity share role
                  slug: example_share_role
                  type: share_role
                  organization_id: "123"
                  grants:
                    - action: "entity:view"
                      resource: "opportunity:123456"
                    - action: "entity:edit"
                      resource: "opportunity:123456"
                    - action: "workflow:execution:*"
                    - action: "message:*"
                    - action: "entity:*"
                      resource: "message*"
                    - action: "entity:*"
                      resource: "thread*"
              "Partner role":
                description: Example partner role. This can be given to a partner organization, who can then assign it to their users
                value:
                  id: "123:example_partner_role"
                  name: Example opportunity share role
                  slug: example_partner_role
                  type: partner_role
                  organization_id: "123"
                  partner_org_id: "456"
                  grants:
                    - action: "entity:view"
                      resource: "opportunity*"
                    - action: "entity:edit"
                      resource: "opportunity*"
                    - action: "workflow:execution:*"
                    - action: "message:*"
                    - action: "entity:*"
                      resource: "message*"
                    - action: "entity:*"
                      resource: "thread*"
              "Portal role":
                description: Example portal role. Implicitly used by end users of portals
                value:
                  id: "123:default_end_customer_portal_role"
                  name: Default End Customer Portal Role
                  slug: default_end_customer_portal_role
                  type: portal_role
                  organization_id: "123"
                  grants:
                    - action: "entity:attribute:view"
                      resource: "contact:*/*"
                    - action: "entity:edit"
                      resource: "opportunity*"

      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
    delete:
      operationId: deleteRole
      summary: deleteRole
      description: Delete role by id
      tags:
        - Roles
      parameters:
        - name: roleId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RoleId"
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Role"
  "/v1/permissions/refresh":
    get:
      operationId: refreshPermissions
      summary: refreshPermissions
      description: Makes sure the user has a role in the organization
      tags:
        - Roles
      responses:
        "200":
          description: Refreshed succesfully
  "/v1/permissions/assignments/{userId}":
    get:
      operationId: getAssignedRolesForUser
      summary: getAssignedRolesForUser
      description: Get list of assigned roles by user id
      tags:
        - Assignments
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/UserId"
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Assignments"
    put:
      operationId: assignRoles
      summary: assignRoles
      description: Assign / unassign roles to users.
      tags:
        - Assignments
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/UserId"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Assignments"
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Assignments"
  "/v1/permissions/assignments/{userId}/{roleId}":
    post:
      operationId: addAssignment
      summary: addAssignment
      description: |
        Assign a user to a role.

        Use the `x-epilot-org-id` header to assign share roles to users in other orgs
      tags:
        - Assignments
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/UserId"
        - name: roleId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RoleId"
      responses:
        "201":
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Assignment"
    delete:
      operationId: removeAssignment
      summary: removeAssignment
      description: Remove role assignment from user
      tags:
        - Assignments
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/UserId"
        - name: roleId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RoleId"
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Assignment"
  "/v1/permissions/assignments":
    get:
      operationId: listAllAssignments
      summary: listAllAssignments
      description: Returns list of all assignments in organization
      tags:
        - Assignments
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  assignments:
                    type: array
                    items:
                      $ref: "#/components/schemas/Assignment"
  "/v1/internal/permissions/assignments":
    get:
      operationId: getAllAssignments
      summary: getAllAssignments
      description: Returns list of all assignments in all organizations
      x-internal: true
      tags:
        - Internal
        - Assignments
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  assignments:
                    type: array
                    items:
                      $ref: "#/components/schemas/OrgAssignments"
  "/v1/internal/permissions/roles":
    get:
      operationId: getAllRoles
      summary: getAllRoles
      description: Returns list of all roles in all organizations
      x-internal: true
      tags:
        - Internal
        - Roles
      parameters:
        - name: limit
          description: The maximum number of user to get
          in: query
          required: false
          schema:
            type: string
          example: 25
        - name: start_key
          description: The primary key of the first item that this operation will evaluate
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: ok
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items:
                      $ref: "#/components/schemas/OrgRoles"
                  lastEvaluatedKey:
                    type: object
                    description: The key to use for pagination
                    properties:
                      pk:
                        type: string
                        example: "ROLES"
                      sk:
                        type: string
                        example: "ORG#ROLE#ROLE_ID"

components:
  securitySchemes:
    EpilotAuth:
      type: http
      scheme: bearer
      description: Authorization header with epilot OAuth2 bearer token
      bearerFormat: JWT
    EpilotOrg:
      description: Overrides the target organization to allow shared tenantaccess
      name: x-epilot-org-id
      in: header
      type: apiKey
  schemas:
    Grant:
      type: object
      properties:
        action:
          type: string
          example: entity-read
        resource:
          type: string
          example: entity:123:contact:f7c22299-ca72-4bca-8538-0a88eeefc947
        effect:
          type: string
          default: allow
          enum:
            - allow
            - deny
        conditions:
          type: array
          items:
            $ref: "#/components/schemas/GrantCondition"
      required:
        - action

    GrantWithDependencies:
      allOf:
        - $ref: "#/components/schemas/Grant"
        - type: object
          properties:
            dependencies:
              description: Provided additional dependencies, exploded when storing the role
              type: array
              items:
                $ref: "#/components/schemas/Grant"

    GrantCondition:
      allOf:
        - description: An additional condition that must be met for the grant
          type: object
          required:
            - operation
        - anyOf:
            - $ref: "#/components/schemas/EqualsCondition"

    EqualsCondition:
      description: Check if attribute equals to any of the values
      type: object
      properties:
        attribute:
          type: string
          example: workflows.primary.task_name
        operation:
          type: string
          enum:
            - equals
        values:
          type: array
          items:
            example: Qualification
      required:
        - attribute
        - operation
        - values

    RoleId:
      type: string
      example: 123:owner
      description: "Format: <organization_id>:<slug>"

    BaseRole:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/RoleId"
        name:
          type: string
          example: Owner
          description: Human-friendly name for the role
        slug:
          type: string
          example: owner
          description: URL-friendly name for the role
        type:
          type: string
          description: Type of the role
        expires_at:
          type: string
          format: date-time
          example: "2028-07-21T17:32:28Z"
          description: date and time then the role will expire
        organization_id:
          $ref: "#/components/schemas/OrganizationId"
        grants:
          type: array
          items:
            $ref: "#/components/schemas/Grant"
          description: List of grants (permissions) applied to the role
      required:
        - id
        - name
        - slug
        - type
        - organization_id
        - grants

    BaseRoleForCreate:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/RoleId"
        name:
          type: string
          example: Owner
          description: Human-friendly name for the role
        slug:
          type: string
          example: owner
          description: URL-friendly name for the role
        type:
          type: string
          description: Type of the role
        expires_at:
          type: string
          format: date-time
          example: "2028-07-21T17:32:28Z"
          description: date and time then the role will expire
        organization_id:
          $ref: "#/components/schemas/OrganizationId"
        grants:
          type: array
          items:
            $ref: "#/components/schemas/Grant"
          description: List of grants (permissions) applied to the role
      required:
        - name
        - slug
        - type
        - grants

    UserRole:
      allOf:
        - $ref: "#/components/schemas/BaseRole"
        - description: A standard user role. Must be explicitly assigned to users.
          properties:
            type:
              enum:
                - user_role

    OrgRole:
      allOf:
        - $ref: "#/components/schemas/BaseRole"
        - description: A role automatically applied to all users in an organization.
          properties:
            type:
              enum:
                - org_role
            pricing_tier:
              type: string
              description: The pricing tier of the organization this root role is based on
              example: Professional

    ShareRole:
      allOf:
        - $ref: "#/components/schemas/BaseRole"
        - description: A role that can be assigned to users in other organizations for sharing purposes.
          properties:
            type:
              enum:
                - share_role

    PartnerRole:
      allOf:
        - $ref: "#/components/schemas/BaseRole"
        - description: A role that appears in another organization's role list that can be assigned but not modified by the partner organization.
          properties:
            type:
              enum:
                - partner_role
            partner_org_id:
              allOf:
                - description: Partner organization who can assign this role to their users.
                - $ref: "#/components/schemas/OrganizationId"

    PortalRole:
      allOf:
        - $ref: "#/components/schemas/BaseRole"
        - description: A role that is applied to end customers and installers using the Portals
          properties:
            type:
              enum:
                - portal_role

    # Role:
    #   oneOf:
    #     - $ref: "#/components/schemas/UserRole"
    #     - $ref: "#/components/schemas/OrgRole"
    #     - $ref: "#/components/schemas/ShareRole"
    #     - $ref: "#/components/schemas/PartnerRole"
    #     - $ref: "#/components/schemas/PortalRole"

    Role:
      allOf:
        - $ref: "#/components/schemas/BaseRole"
        - type: object
          description: Represents any type of role that a user or partner might have.
          properties:
            type:
              type: string
              enum:
                - user_role
                - org_role
                - share_role
                - partner_role
                - portal_role
            pricing_tier:
              type: string
              description: The pricing tier of the organization this root role is based on
              example: Professional
            partner_org_id:
              allOf:
                - description: Partner organization who can assign this role to their users.
                - $ref: "#/components/schemas/OrganizationId"
          required:
            - type

    RolePayload:
      allOf:
        - $ref: "#/components/schemas/BaseRole"
        - type: object
          description: A payload to create or update a role with attached grants.
          properties:
            type:
              type: string
              enum:
                - user_role
                - org_role
                - share_role
                - partner_role
                - portal_role
            grants:
              type: array
              items:
                $ref: "#/components/schemas/GrantWithDependencies"
            pricing_tier:
              type: string
              description: The pricing tier of the organization this root role is based on
              example: Professional
            partner_org_id:
              allOf:
                - description: Partner organization who can assign this role to their users.
                - $ref: "#/components/schemas/OrganizationId"
          required:
            - type
            - grants

    Assignment:
      type: object
      description: A role attached to an user
      properties:
        user_id:
          $ref: "#/components/schemas/UserId"
        roles:
          type: array
          items:
            $ref: "#/components/schemas/RoleId"
    InternalAssignment:
      type: object
      description: A role attached to an user
      properties:
        userId:
          $ref: "#/components/schemas/UserId"
        roles:
          type: array
          items:
            $ref: "#/components/schemas/RoleId"
    OrgAssignments:
      type: object
      description: All roles attached to an users of an organization
      properties:
        organizationId:
          $ref: "#/components/schemas/OrganizationId"
        assignments:
          type: array
          items:
            $ref: "#/components/schemas/InternalAssignment"
    OrgRoles:
      type: object
      description: All roles attached to an users of an organization
      properties:
        organizationId:
          $ref: "#/components/schemas/OrganizationId"
        roles:
          type: array
          items:
            $ref: "#/components/schemas/Role"
    Assignments:
      type: array
      description: List of role ids attached to an user
      items:
        $ref: "#/components/schemas/RoleId"

    UserId:
      type: string
      example: "1"
      description: Id of a user

    OrganizationId:
      type: string
      example: "123"
      description: Id of an organization

    Slug:
      type: string
      example: "owner"
      description: Slug of a role; for a role with id = 123:manager -> 123 is org_id & manager is slug

    RoleSearchInput:
      type: object
      properties:
        role_ids:
          type: array
          description: List of role ids to filter by
          example: ["123:manager", "456:owner"]
          items:
            $ref: "#/components/schemas/RoleId"
        org_ids:
          type: array
          description: List of organization ids to filter by
          example: ["123", "456"]
          items:
            $ref: "#/components/schemas/OrganizationId"
        slugs:
          type: array
          description: List of role slugs to filter by
          example: ["manager", "owner"]
          items:
            $ref: "#/components/schemas/Slug"
        query:
          type: string
          description: Input to search across fields
          example: "Administrator"
        limit:
          type: number
          description: The Number of roles to return
          example: 1
          minimum: 1
          default: 50
        offset:
          type: number
          description: The number of roles to skip before starting to collect the result set
          example: 1
          minimum: 1
          default: 0

    CreateRolePayload:
      allOf:
        - $ref: "#/components/schemas/BaseRoleForCreate"
        - type: object
          description: A payload to create or update a role with attached grants.
          properties:
            type:
              type: string
              enum:
                - user_role
                - org_role
                - share_role
                - partner_role
                - portal_role
            grants:
              type: array
              items:
                $ref: "#/components/schemas/GrantWithDependencies"
            pricing_tier:
              type: string
              description: The pricing tier of the organization this root role is based on
              example: Professional
            partner_org_id:
              allOf:
                - description: Partner organization who can assign this role to their users.
                - $ref: "#/components/schemas/OrganizationId"
          required:
            - type
            - grants