Blng Workspace API

openapi: 3.2.0
info:
  title: User Workspace API
  description: Api to manage roles and permissions of users
  version: 1.0.0
servers:
- url: https://users.blng.ai
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: Workspace
paths:
  /users/{userId}/memberships:
    get:
      tags:
      - Workspace
      summary: List workspace memberships for user (multi-tenancy; returns [] when feature off)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (empty array when multi-tenancy is disabled for the stage)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkspaceMembership'
        '500':
          description: Internal Server Error
  /users/{userId}/workspaces:
    get:
      tags:
      - Workspace
      summary: List workspaces for user (summaries for switcher; returns [] when feature off)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (empty array when multi-tenancy is disabled for the stage)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserWorkspaceSwitcherItem'
        '500':
          description: Internal Server Error
    post:
      tags:
      - Workspace
      summary: Create a team, enterprise, or enterprise-team workspace (creator becomes owner)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkspaceRequest'
      responses:
        '201':
          description: Workspace created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserWorkspaceSwitcherItem'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Multi-tenancy disabled, deleted account, insufficient access to parent enterprise, or workspace creation limit reached (soft cap on memberships with role owner; configurable per stage and per user via `allowedWorkspaces` on the User record).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User or parent workspace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/workspaces/{workspaceId}:
    get:
      tags:
      - Workspace
      summary: Get a single workspace (for user) by workspaceId
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserWorkspaceSwitcherItem'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace not found for user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
    put:
      tags:
      - Workspace
      summary: Update editable workspace fields (currently name only)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkspaceRequest'
      responses:
        '200':
          description: Workspace updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserWorkspaceSwitcherItem'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Multi-tenancy disabled or insufficient role for update
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace not found for user (or workspace row missing)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/workspaces/{workspaceId}/members:
    get:
      tags:
      - Workspace
      summary: List members for a workspace visible to the requesting user (paginated)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: limit
        in: query
        required: false
        description: Page size (default 50, max 100)
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: nextToken
        in: query
        required: false
        description: Opaque token from the previous response to fetch the next page
        schema:
          type: string
      responses:
        '200':
          description: Success (members empty when multi-tenancy is disabled for the stage). `email` and `displayName` use denormalized fields on membership when present to avoid per-page Users BatchGet; legacy rows without those fields are hydrated from Users for that page only.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceMembersList'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace not found for user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/workspaces/{workspaceId}/invitations:
    get:
      tags:
      - Workspace
      summary: List pending workspace invitations (owner/admin)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Pending invitations for the workspace
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkspacePendingInvitationAdmin'
        '403':
          description: Multi-tenancy disabled or insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace not found for user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
    post:
      tags:
      - Workspace
      summary: Invite a member by email (team, enterprise, enterprise-team only; owner/admin; SES when configured)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkspaceInvitationRequest'
      responses:
        '201':
          description: Invitation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceInvitationCreated'
        '400':
          description: Bad Request (e.g. invalid body or cannot invite your own email)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Multi-tenancy disabled, insufficient role, or workspace type does not support invitations (personal starter/pro/beta)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace or authenticated user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Pending invite exists or user already a member
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/workspaces/{workspaceId}/invitations/{invitationId}:
    delete:
      tags:
      - Workspace
      summary: Revoke a pending workspace invitation (owner/admin)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: invitationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Invitation revoked
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Multi-tenancy disabled or insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace or invitation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Invitation is not pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/workspaces/{workspaceId}/invitations/{invitationId}/resend:
    post:
      tags:
      - Workspace
      summary: Resend workspace invite email (team/ent workspaces only; owner/admin; SES)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: invitationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Resend attempted
          content:
            application/json:
              schema:
                type: object
                required:
                - emailSent
                properties:
                  emailSent:
                    type: boolean
                    description: Whether SES accepted the send (false if misconfigured or SES failure)
        '400':
          description: Bad Request (e.g. invitation not pending, expired, or DESIGN_APP_WEB_ORIGIN missing)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Multi-tenancy disabled, insufficient role, or workspace type does not support invitations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace or invitation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many resend attempts for this invitation (cooldown between successful invitation emails)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/workspace-invitations/inbox:
    get:
      tags:
      - Workspace
      summary: List pending workspace invitations for the signed-in user's email (accept from settings without opening the email link)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Pending invitations the user can accept (non-expired, workspace still valid, not already a member)
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required:
                  - workspaceInvitationId
                  - workspaceId
                  - workspaceName
                  - role
                  - createdAt
                  properties:
                    workspaceInvitationId:
                      type: string
                      format: uuid
                    workspaceId:
                      type: string
                      format: uuid
                    workspaceName:
                      type: string
                    role:
                      type: string
                    createdAt:
                      type: string
                    expiresAt:
                      type: integer
                      description: Unix epoch seconds when the invite link expires
        '403':
          description: Multi-tenancy disabled or account not active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/workspace-invitations/{invitationId}/email-match:
    get:
      tags:
      - Workspace
      summary: Check whether the signed-in user's email matches a pending workspace invitation; when true, returns workspace display name (public GET does not expose the name)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: invitationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Match result
          content:
            application/json:
              schema:
                type: object
                required:
                - matches
                properties:
                  matches:
                    type: boolean
                  workspaceName:
                    type: string
                    description: Present only when matches is true; workspace display name for the invite UI
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Path userId does not match authenticated user or multi-tenancy disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User, invitation not found, or invitation not pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/workspace-invitations/{invitationId}/accept:
    post:
      tags:
      - Workspace
      summary: Accept a workspace invitation (authenticated; email must match; target must be team/ent workspace)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: invitationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Membership created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceMembership'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Email mismatch, multi-tenancy disabled, orphaned account, or target workspace does not support members (personal)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Invitation or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Invitation not pending, expired, already a member, invalid role, or transactional conflict (e.g. accepted concurrently in another session)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: DynamoDB throughput limit; client should retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /workspace-invitations/{invitationId}:
    get:
      tags:
      - Workspace
      summary: Public invitation metadata for the invite landing page (no auth; workspace name omitted)
      parameters:
      - name: invitationId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Invitation details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceInvitationPublic'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Multi-tenancy is not enabled for this deployment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Invitation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/workspaces/{workspaceId}/members/{memberUserId}:
    put:
      tags:
      - Workspace
      summary: Update a member role (owner/admin; owner-only rules for OWNER role)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: memberUserId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMembershipRoleRequest'
      responses:
        '200':
          description: Membership updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceMembership'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Multi-tenancy disabled or insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace or member not found for user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Would remove the last workspace owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
    delete:
      tags:
      - Workspace
      summary: Remove a workspace member (owner/admin; owner-only removal of owners)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: memberUserId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Member removed
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Multi-tenancy disabled or insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace or member not found for user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Cannot remove the last workspace owner
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/workspaces/{workspaceId}/integrity:
    get:
      tags:
      - Workspace
      summary: Workspace integrity summary (owner/admin; reporting only)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Integrity report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceIntegrityReport'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Multi-tenancy disabled or insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace not found for user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/workspaces/{workspaceId}/sso-config:
    put:
      tags:
      - Workspace
      summary: Rotate the workspace's enterprise SAML config (owner/admin; self-service)
      description: Updates the SAML IdP metadata (and optionally the email attribute mapping) for the provider the caller's workspace federates through. The provider is resolved only from the caller's own membership, never the request body.
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - metadataXml
              properties:
                metadataXml:
                  type: string
                  description: Inline SAML IdP metadata document (EntityDescriptor XML), not a URL.
                emailAttribute:
                  type: string
                  description: Optional SAML assertion attribute carrying email; omitted keeps the current mapping.
      responses:
        '200':
          description: SSO configuration updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  providerName:
                    type: string
                  updated:
                    type: boolean
        '400':
          description: Invalid body, no provider for workspace, or metadata rejected by Cognito
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Multi-tenancy disabled or insufficient role
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workspace or enterprise SSO provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
  /users/{userId}/active-workspace:
    put:
      tags:
      - Workspace
      summary: Set active workspace (403 when multi-tenancy disabled for stage)
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetActiveWorkspaceRequest'
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Multi-tenancy not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found, or no membership for the requested workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    WorkspacePendingInvitationAdmin:
      type: object
      required:
      - workspaceInvitationId
      - workspaceId
      - email
      - role
      - status
      - inviteTarget
      - createdAt
      - updatedAt
      properties:
        workspaceInvitationId:
          type: string
          format: uuid
        workspaceId:
          type: string
          format: uuid
        email:
          type: string
        role:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - ACCEPTED
          - REJECTED
        inviteTarget:
          type: string
          enum:
          - new_user
          - existing_user
        createdAt:
          type: string
        updatedAt:
          type: string
    WorkspaceMembersList:
      type: object
      required:
      - members
      description: Paginated list from GET .../workspaces/{workspaceId}/members
      properties:
        members:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceMembership'
        nextToken:
          type: string
          description: Present when more pages exist; pass as the nextToken query parameter
    CreateWorkspaceRequest:
      type: object
      required:
      - name
      - type
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: Display name for the new workspace
        type:
          type: string
          enum:
          - team
          - enterprise
          - enterprise-team
        parentWorkspaceId:
          type: string
          format: uuid
          description: Required when type is enterprise-team; must be an enterprise workspace the user administers
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
    UpdateWorkspaceRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: Workspace display name
    WorkspaceMembership:
      type: object
      description: Membership row (PK userId, SK workspaceId). Returned by GET /users/{userId}/memberships.
      required:
      - userId
      - workspaceId
      - role
      - createdAt
      - updatedAt
      properties:
        userId:
          type: string
        workspaceId:
          type: string
          format: uuid
        role:
          type: string
          enum:
          - OWNER
          - BILLING_ADMIN
          - ADMIN
          - EDITOR
          - VIEWER
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        memberType:
          type: string
          enum:
          - sso_employee
          - external
          - federated_b2b2c
          description: Optional; SSO / external / federated classification
        federatedIdpId:
          type: string
          description: Opt

# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/blng/refs/heads/main/openapi/blng-workspace-api-openapi.yml