LaserData Roles API

openapi: 3.1.0
info:
  title: LaserData Cloud Audit Account Roles API
  description: 'Tenant audit log and per-user activity feed.


    Public REST API for the LaserData Cloud audit service.


    ## Authentication


    Every endpoint accepts either of two auth methods:

    - **API key** (machine / CI / SDK): send in the `ld-api-key` header. Cannot be used on `GET /audit/users/activity` which is session-only.

    - **Session cookie** (browser / console): obtained from `POST /account/sign_in` on the control plane.


    Audit endpoints are read-only and replay-safe by definition.


    ## Pagination


    List endpoints return a `Paged<T>` body (`page`, `total_pages`, `total_results`, `items`) and a `link` header (RFC 8288) with `rel="first"`, `"prev"`, `"next"`, `"last"` when applicable.


    ## Errors


    Error responses follow RFC 7807 `application/problem+json` with `type`, `title`, `code`, `reason`, `instance`, `status`, `retryable`, and optional `field` / `field_issues`. `retryable` is `true` for 408, 425, 429, 500, 502, 503, 504.


    ## Response headers


    - `ld-request`: request ID. Include it when reporting issues.

    - `link`: pagination relations.

    - `retry-after`: wait hint on 429 / 503.'
  termsOfService: https://laserdata.com/terms
  contact:
    name: LaserData Support
    url: https://docs.laserdata.com
    email: support@laserdata.com
  license:
    name: Proprietary
  version: 0.0.66
  x-logo:
    url: https://assets.laserdata.com/laserdata_dark.png
    altText: LaserData
    href: https://laserdata.com
servers:
- url: https://api.laserdata.cloud
  description: Production
security:
- ld_api_key: []
- session_cookie: []
tags:
- name: Roles
  description: Tenant roles and permissions
paths:
  /tenants/{tenant_id}/roles:
    get:
      tags:
      - Roles
      summary: List roles
      description: Returns the tenant's roles. System roles (Owner, Admin, Member, Viewer) plus any custom roles. Filter by `kind` to separate system from custom.
      operationId: get_roles
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: page
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 1
        example: 1
      - name: results
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 1
        example: 10
      - name: kind
        in: query
        required: false
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: Paged roles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paged_RoleBasicInfo'
        '403':
          description: Insufficient permissions
    post:
      tags:
      - Roles
      summary: Create role
      description: Creates a custom role with a permission tree spanning tenant + division + environment scopes. New id returned in `ld-role` header. System roles cannot be created via this API.
      operationId: add_role
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      requestBody:
        description: Name + permissions tree. System role kind is rejected - all created roles are Custom.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddRole'
        required: true
      responses:
        '201':
          description: Role created. The new role ID is returned in the ld-role header
        '400':
          description: Invalid name, invalid permissions tree, or roles limit reached
        '403':
          description: Insufficient permissions
        '409':
          description: Name already used
  /tenants/{tenant_id}/roles/{role_id}:
    get:
      tags:
      - Roles
      summary: Get role
      description: Returns role details including full permission tree (tenant + division + environment scopes).
      operationId: get_role
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: role_id
        in: path
        description: Role identifier
        required: true
        schema:
          $ref: '#/components/schemas/RoleId'
      responses:
        '200':
          description: Role with permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoleDetails'
        '403':
          description: Insufficient permissions
        '404':
          description: Role not found
    put:
      tags:
      - Roles
      summary: Update role
      description: Updates a custom role's name or permissions tree. System roles cannot be modified.
      operationId: update_role
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: role_id
        in: path
        description: Role identifier
        required: true
        schema:
          $ref: '#/components/schemas/RoleId'
      requestBody:
        description: Partial update. Null or missing fields are unchanged
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRole'
        required: true
      responses:
        '204':
          description: Role updated
        '400':
          description: Invalid name or permissions
        '403':
          description: Cannot modify system role or insufficient permissions
        '404':
          description: Role not found
    delete:
      tags:
      - Roles
      summary: Delete role
      description: Deletes a custom role. Members assigned to it lose its permissions. System roles cannot be deleted.
      operationId: delete_role
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: role_id
        in: path
        description: Role identifier
        required: true
        schema:
          $ref: '#/components/schemas/RoleId'
      responses:
        '204':
          description: Role deleted
        '403':
          description: Cannot delete system role or insufficient permissions
        '404':
          description: Role not found
  /tenants/{tenant_id}/roles/{role_id}/members:
    get:
      tags:
      - Roles
      summary: List role members
      description: Returns the users currently assigned to this role.
      operationId: get_role_members
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: role_id
        in: path
        description: Role identifier
        required: true
        schema:
          $ref: '#/components/schemas/RoleId'
      - name: page
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 1
        example: 1
      - name: results
        in: query
        required: false
        schema:
          type:
          - integer
          - 'null'
          format: int64
          minimum: 1
        example: 10
      responses:
        '200':
          description: Paged role members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Paged_RoleMemberInfo'
        '403':
          description: Insufficient permissions
        '404':
          description: Role not found
  /tenants/{tenant_id}/roles/{role_id}/members/assign:
    put:
      tags:
      - Roles
      summary: Assign members to role
      description: Adds existing members to the role. Members keep any other roles they already have.
      operationId: assign_role_members
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: role_id
        in: path
        description: Role identifier
        required: true
        schema:
          $ref: '#/components/schemas/RoleId'
      requestBody:
        description: List of member user ids to add to the role
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignRoleMembers'
        required: true
      responses:
        '204':
          description: Members assigned to role
        '400':
          description: Empty members list, members not in tenant, or cannot assign self
        '403':
          description: Insufficient permissions
  /tenants/{tenant_id}/roles/{role_id}/members/revoke:
    put:
      tags:
      - Roles
      summary: Revoke members from role
      description: Removes members from the role. They keep their other role assignments and tenant membership.
      operationId: revoke_role_members
      parameters:
      - name: tenant_id
        in: path
        description: Tenant identifier
        required: true
        schema:
          $ref: '#/components/schemas/TenantId'
      - name: role_id
        in: path
        description: Role identifier
        required: true
        schema:
          $ref: '#/components/schemas/RoleId'
      requestBody:
        description: List of member user ids to remove from the role
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokeRoleMembers'
        required: true
      responses:
        '204':
          description: Members revoked from role
        '400':
          description: Empty members list or cannot revoke from self
        '403':
          description: Insufficient permissions
components:
  schemas:
    RevokeRoleMembers:
      type: object
      required:
      - members
      properties:
        members:
          type: array
          items:
            $ref: '#/components/schemas/UserId'
    RoleBasicInfo:
      type: object
      required:
      - id
      - name
      - kind
      properties:
        id:
          $ref: '#/components/schemas/RoleId'
        kind:
          $ref: '#/components/schemas/TenantRoleKind'
        name:
          $ref: '#/components/schemas/RoleName'
      example:
        id: 611298765432109010
        name: developer
        kind: system
    EnvironmentPermissionsInfo:
      type: object
      required:
      - name
      - permissions
      properties:
        name:
          $ref: '#/components/schemas/EnvironmentName'
        permissions:
          type: array
          items:
            type: string
    Paged_RoleBasicInfo:
      type: object
      required:
      - total_pages
      - total_results
      - page
      - items
      properties:
        items:
          type: array
          items:
            type: object
            required:
            - id
            - name
            - kind
            properties:
              id:
                $ref: '#/components/schemas/RoleId'
              kind:
                $ref: '#/components/schemas/TenantRoleKind'
              name:
                $ref: '#/components/schemas/RoleName'
            example:
              id: 611298765432109010
              name: developer
              kind: system
        page:
          type: integer
          format: int64
          example: 1
          minimum: 1
        total_pages:
          type: integer
          format: int64
          example: 4
          minimum: 0
        total_results:
          type: integer
          format: int64
          example: 137
          minimum: 0
    DivisionPermissionsInfo:
      type: object
      required:
      - name
      - permissions
      - environment
      - environments
      properties:
        environment:
          type: array
          items:
            type: string
        environments:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/EnvironmentPermissionsInfo'
          propertyNames:
            type: string
        name:
          $ref: '#/components/schemas/DivisionName'
        permissions:
          type: array
          items:
            type: string
    TenantRoleKind:
      type: string
      enum:
      - system
      - custom
      - api_key
    RoleName:
      type: string
      example: tenant-admin
    Paged_RoleMemberInfo:
      type: object
      required:
      - total_pages
      - total_results
      - page
      - items
      properties:
        items:
          type: array
          items:
            type: object
            required:
            - id
            - email
            - name
            - active
            properties:
              active:
                type: boolean
              email:
                $ref: '#/components/schemas/Email'
              id:
                $ref: '#/components/schemas/UserId'
              name:
                $ref: '#/components/schemas/FullName'
            example:
              id: 611298765432109069
              email: alice@acme.com
              name: Alice Doe
              active: true
        page:
          type: integer
          format: int64
          example: 1
          minimum: 1
        total_pages:
          type: integer
          format: int64
          example: 4
          minimum: 0
        total_results:
          type: integer
          format: int64
          example: 137
          minimum: 0
    AssignRoleMembers:
      type: object
      required:
      - members
      properties:
        members:
          type: array
          items:
            $ref: '#/components/schemas/UserId'
    Email:
      type: string
      example: alice@laserdata.com
    DivisionName:
      type: string
      example: production
    DivisionPermissions:
      type: object
      properties:
        environment:
          type:
          - array
          - 'null'
          items:
            type: string
        environments:
          type:
          - object
          - 'null'
          additionalProperties:
            type: array
            items:
              type: string
          propertyNames:
            type: string
        permissions:
          type:
          - array
          - 'null'
          items:
            type: string
    FullName:
      type: string
      example: Alice Doe
    UpdateRole:
      type: object
      properties:
        name:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/RoleName'
        permissions:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/RolePermissions'
    RoleDetails:
      allOf:
      - $ref: '#/components/schemas/RoleBasicInfo'
      - type: object
        required:
        - permissions
        properties:
          permissions:
            $ref: '#/components/schemas/RolePermissionsInfo'
    EnvironmentName:
      type: string
      example: staging
    RolePermissions:
      type: object
      properties:
        division:
          type:
          - array
          - 'null'
          items:
            type: string
        divisions:
          type:
          - object
          - 'null'
          additionalProperties:
            $ref: '#/components/schemas/DivisionPermissions'
          propertyNames:
            type: string
        environment:
          type:
          - array
          - 'null'
          items:
            type: string
        tenant:
          type:
          - array
          - 'null'
          items:
            type: string
    RoleId:
      type: integer
      format: int64
      example: 7261845001236500000
      minimum: 0
    AddRole:
      type: object
      required:
      - name
      - permissions
      properties:
        name:
          $ref: '#/components/schemas/RoleName'
        permissions:
          $ref: '#/components/schemas/RolePermissions'
    RolePermissionsInfo:
      type: object
      required:
      - tenant
      - division
      - environment
      - divisions
      properties:
        division:
          type: array
          items:
            type: string
        divisions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DivisionPermissionsInfo'
          propertyNames:
            type: string
        environment:
          type: array
          items:
            type: string
        tenant:
          type: array
          items:
            type: string
    TenantId:
      type: integer
      format: int64
      example: 7261845022003200001
      minimum: 0
    UserId:
      type: integer
      format: int64
      example: 7261844898910240000
      minimum: 0
  securitySchemes:
    ld_api_key:
      type: apiKey
      in: header
      name: ld-api-key
      description: Tenant API key sent in the ld-api-key request header. Scoped to tenant-level audit reads. Cannot be used on user-scope endpoints (`/audit/users/activity`).
    session_cookie:
      type: apiKey
      in: cookie
      name: session
      description: Browser session cookie issued by POST /account/sign_in on core. Required for user-scope endpoints.
externalDocs:
  url: https://docs.laserdata.com
  description: LaserData Cloud documentation