REST API that manages BLNG users, roles and permissions, workspaces and workspace members, workspace and subscription invitations, organizations, SSO configuration, marketing consent, tooltips, and user subscriptions. Also exposes composite operations that create an organization, subscription and user in a single call. Authenticated with AWS Cognito user tokens, plus a client-credentials machine token for the billing integration.
openapi: 3.0.1
info:
title: User Api
description: Api to manage roles and permissions of users
version: 1.0.0
paths:
"/users/{userId}":
get:
tags:
- User
summary: get user
security:
- cognitoUserAuth:
- openid
parameters:
- name: userId
in: path
required: true
schema:
type: string
description: Unique identifier for the User
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Bad Request
'404':
description: User not found
'500':
description: Internal Server Error
put:
tags:
- User
summary: Update user
security:
- cognitoUserAuth:
- openid
parameters:
- name: userId
in: path
required: true
schema:
type: string
description: Unique identifier for the User
requestBody:
content:
application/json:
schema:
type: object
example:
email: updated_email@example.com
tooltipFlowIdViewed: onboarding-flow-id-1
responses:
'200':
description: User updated
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
description: Bad Request
'404':
description: User not found
'500':
description: Internal Server Error
"/users/{userId}/subscriptions":
get:
tags:
- User Subscription
summary: Get subscriptions associated with user
security:
- cognitoUserAuth:
- openid
parameters:
- name: userId
in: path
required: true
schema:
type: string
description: Unique identifier for the User
responses:
'200':
description: Success
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserSubscriptionListItem'
'400':
description: Bad Request
'404':
description: User not found
'500':
description: Internal Server Error
post:
tags:
- User Subscription
summary: Associate a subscription with a user
deprecated: true
security:
- cognitoUserAuth:
- openid
parameters:
- name: userId
in: path
required: true
schema:
type: string
description: Unique identifier for the User
requestBody:
content:
application/json:
schema:
type: object
required:
- subscriptionId
- roles
example:
subscriptionId: f39b8a30-b917-4eab-87c9-0df3cdf0e93e
roles:
- OWNER
responses:
'201':
description: Subscription linked for user
content:
application/json:
schema:
items:
$ref: '#/components/schemas/Subscription'
'400':
description: Bad Request
'404':
description: User or subscription not found (if applicable)
'409':
description: Conflict (e.g. subscription already linked)
'500':
description: Internal Server Error
"/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:
# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/blng/refs/heads/main/openapi/blng-user-api-openapi.yml