BLNG User API

openapi: 3.2.0
info:
  title: Api User API
  description: Api to manage roles and permissions of users
  version: 1.0.0
tags:
- name: User
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
      operationId: getUsersByUserId
      x-operation-id-source: derived
    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. Also returned with `{"message": "This name is reserved"}` when firstName, lastName or the combined name matches one of the assistant''s names (BLNG, BLNG AI, BLNG · AI, BLNG Assistant, BLNG AI Assistant, BLNG Bot). Names are compared after NFKD with combining marks removed, ignoring case, spacing, punctuation and invisible characters, with look-alike letters from other scripts (Cyrillic, Greek, Cherokee, Lisu, small capitals) read as their Latin counterparts and strokes such as l, 1 and | read as either l or I (Latin capital I always reads as I). Direction marks (U+200E, U+200F, U+061C) are ignored, and the words they separate are also checked in reverse order. Any name containing a text-direction override, embedding or isolate (U+202A-202E, U+2066-2069) is refused.'
        '404':
          description: User not found
        '409':
          description: 'Conflict, `{"message": "The profile changed while saving; please retry"}`. The name was changed by another request while this one was being checked, and the retries ran out. Retrying the request is safe.'
        '500':
          description: Internal Server Error
      operationId: putUsersByUserId
      x-operation-id-source: derived
  /users/{userId}/marketing-consent:
    get:
      tags:
      - User
      summary: Get marketing consent state and whether the one-time prompt is due
      description: '`shouldPrompt` is true only for a live user who is still signing up and has neither answered nor been asked. A user row that does not exist yet answers `{ "optIn": null, "shouldPrompt": false }` rather than an error.'
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      - name: include
        in: query
        required: false
        description: Comma separated list of optional fields to resolve. `deliverable` costs a live HubSpot read, so it is not served unless asked for. An unknown value is ignored.
        schema:
          type: string
        example: deliverable
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketingConsentState'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getUsersByUserIdMarketingConsent
      x-operation-id-source: derived
    put:
      tags:
      - User
      summary: Record a marketing consent choice, or that the prompt was dismissed
      description: An answer stores a consent receipt on the user record, which the HubSpot reconciliation cron syncs to the `marketing_opt_in` contact property. A dismissal records only that the prompt was shown, so no property value reaches HubSpot and no choice is fabricated; it never overwrites an answer. The receipt timestamp is server-stamped and cannot be supplied by the caller.
      security:
      - cognitoUserAuth:
        - openid
      parameters:
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutMarketingConsentRequest'
      responses:
        '200':
          description: Consent state after the write
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketingConsentState'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Account deleted
          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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: putUsersByUserIdMarketingConsent
      x-operation-id-source: derived
  /composite/createOrgAndSubscriptionWithUser:
    post:
      tags:
      - User
      summary: Creates an organization, a subscription, and a user, and attaches them in one…
      deprecated: true
      description: Creates a new organization , a new subscription , and attaches an existing user to the subscription with an admin role. This is **not strictly REST** because it handles multiple resources in one call, but it simplifies our client needs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                organizationName:
                  type: string
                  description: Name of the organization
                subscriptionName:
                  type: string
                  description: Subscription name to create or attach
                userId:
                  type: string
                  description: Unique identifier for the User
              required:
              - organizationName
              - subscriptionName
              - userId
              example:
                organizationName: BigCo Inc.
                subscriptionName: My Super Subscription
                userId: abc123
      responses:
        '201':
          description: Composite creation succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  organization:
                    $ref: '#/components/schemas/Organization'
                  subscription:
                    $ref: '#/components/schemas/Subscription'
                  userId:
                    type: string
                    description: Unique identifier for the User
        '400':
          description: Bad Request
        '404':
          description: User not found
        '409':
          description: Conflict (e.g., organization or subscription already exists in a conflicting state)
        '500':
          description: Internal Server Error
      operationId: postCompositeCreateOrgAndSubscriptionWithUser
      x-operation-id-source: derived
  /composite/createUserAndSubscription:
    post:
      tags:
      - User
      summary: Creates a user, a subscription, and attaches them in one transaction.
      deprecated: true
      description: Creates a new user (if not exists) and a new subscription (if not exists), and attaches the user to the subscription with the specified roles. This is **not strictly REST** because it handles multiple resources in one call, but it simplifies our client needs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  description: Unique identifier for the User
                email:
                  type: string
                firstName:
                  type: string
                lastName:
                  type: string
                subscriptionName:
                  type: string
                  description: Subscription name to create or attach
                roles:
                  type: array
                  items:
                    type: string
                  description: Roles to assign to the user in this subscription
              required:
              - userId
              - email
              - subscriptionName
              example:
                userId: abc123
                email: test@example.com
                firstName: Jane
                lastName: Doe
                subscriptionName: My Super Subscription
                roles:
                - OWNER
      responses:
        '201':
          description: Composite creation succeeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
                  subscription:
                    $ref: '#/components/schemas/Subscription'
        '400':
          description: Bad Request
        '409':
          description: Conflict (e.g., user or subscription already exists in a conflicting state)
        '500':
          description: Internal Server Error
      operationId: postCompositeCreateUserAndSubscription
      x-operation-id-source: derived
components:
  schemas:
    MarketingConsentReceipt:
      type: object
      description: Marketing opt-in receipt (GDPR consent provenance). Present only for users who made an explicit choice; optIn records that choice either way. Synced to HubSpot as the marketing_opt_in contact property. Absent for users who have never been asked or who dismissed the prompt.
      required:
      - optIn
      - timestamp
      - wordingVersion
      - captureLocation
      properties:
        optIn:
          type: boolean
          description: The user's choice
        timestamp:
          type: string
          format: date-time
          description: When the choice was captured. Server-stamped; never accepted from the caller.
        wordingVersion:
          type: string
          description: Version tag of the exact consent wording shown, so the receipt survives copy changes
        captureLocation:
          type: string
          description: Which surface captured the choice. `email-unsubscribe` and `email-spam-complaint` are withdrawals the recipient made against mail we sent, the first through an unsubscribe link and the second by reporting it to their provider. Both are recorded from the CRM's own subscription-change events rather than through this API.
          enum:
          - signup
          - first-login-prompt
          - settings
          - contact-sales
          - email-unsubscribe
          - email-spam-complaint
    PutMarketingConsentRequest:
      oneOf:
      - type: object
        description: An explicit choice
        required:
        - optIn
        - wordingVersion
        - captureLocation
        additionalProperties: false
        properties:
          optIn:
            type: boolean
          wordingVersion:
            type: string
            enum:
            - v1
            - v2
            - v3
          captureLocation:
            type: string
            enum:
            - first-login-prompt
            - settings
            - contact-sales
      - type: object
        description: The prompt was shown and closed without an answer
        required:
        - dismissed
        additionalProperties: false
        properties:
          dismissed:
            type: boolean
            enum:
            - true
    Subscription:
      type: object
      properties:
        subscriptionId:
          type: string
          description: Unique identifier for the subscription
        name:
          type: string
          description: Human-friendly subscription name
        ownerId:
          type: string
          description: id of owner of the subscription
        ownerType:
          type: string
          enum:
          - user
          - organization
          description: Type of owner of the subscription
        subscriptionType:
          type: string
          enum:
          - starter
          - pro
          - team
          - enterprise
          - beta
          description: Type of subscription
        stripeSubscriptionId:
          type: string
          description: Stripe subscription ID
        stripeCustomerId:
          type: string
          description: Stripe customer ID associated with owner
        seatsPurchased:
          type: integer
          description: Number of seats purchased
        paymentSource:
          type: string
          enum:
          - stripe
          - apple
          description: Payment source for subscription. Always stripe for now.
        status:
          type: string
          enum:
          - active
          - canceled
          - incomplete
          - incomplete_expired
          - paused
          - past_due
          - trialing
          - unpaid
          description: Status of subscription. Maps to stripe status.
        cancelAtPeriodEnd:
          type: boolean
          description: Whether the subscription will be canceled at the end of the current period
        currentPeriodEnd:
          type: string
          format: date-time
          description: Timestamp of when the current period ends
        billingInterval:
          type: string
          enum:
          - month
          - year
          description: How often the plan fee is billed. Absent means month. The CU and Fast allowance resets monthly on every interval. Annual plans are not offered yet.
        termStart:
          type: string
          format: date-time
          description: Start of the current billing term (moves at each renewal). Monthly allowance periods count from allowanceAnchor when it is set, and from termStart only when it is not.
        allowanceAnchor:
          type: string
          format: date-time
          description: Stable instant the monthly allowance periods count from, set once per subscription and never moved by a renewal (Stripe billing_cycle_anchor, Apple originalPurchaseDate, or the Metronome contract start of a new subscribe). Each period is a whole number of months from it, clamped to month end per month from the anchor's own day. Only read for annual plans.
        termEnd:
          type:
          - string
          - 'null'
          format: date-time
          description: End of the current billing term (renewal). Absent or null for a monthly Metronome contract.
        canceledAt:
          type: string
          format: date-time
          description: Timestamp of when the subscription was canceled
        entitlements:
          $ref: '#/components/schemas/Entitlements'
        createdAt:
          type: string
          format: date-time
          description: Timestamp of when the subscription was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of the last update to subscription
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
    MarketingConsentState:
      type: object
      required:
      - optIn
      - shouldPrompt
      properties:
        optIn:
          type:
          - boolean
          - 'null'
          description: The user's recorded choice, or null when they have never answered
        shouldPrompt:
          type: boolean
          description: Whether the one-time consent prompt is due for this user
        deliverable:
          type: object
          description: The two gates HubSpot applies before delivering a marketing email, both of which must pass. Read live from the CRM, so this describes the mail rather than the recorded choice. Served only when asked for via `include=deliverable`.
          required:
          - marketingContact
          - subscribed
          properties:
            marketingContact:
              type:
              - boolean
              - 'null'
              description: Whether the contact is a marketing contact. Null when it could not be read, which is not the same as false.
            subscribed:
              type:
              - boolean
              - 'null'
              description: Whether the contact is subscribed to the marketing subscription. Null when it could not be read, which is not the same as false.
    Entitlements:
      type: object
      properties:
        maxJourneys:
          type: integer
          description: Maximum number of journeys allowed on a subscription. -1 for unlimited.
        chatVisibilityWindowHrs:
          type: integer
          description: Maximum number of hours to let a user look back in chat history. -1 for unlimited.
        upscaleAvailable:
          type: boolean
          description: Whether 4k upscale is available on this subscription.
        exportWatermarkRequired:
          type: boolean
          description: Whether exports from this subscription must carry a visible "Made with BLNG" mark. The server computes the policy; whoever hands pixels out applies it, which today is the web and iOS clients at their export paths. Until the watermark launches (the runtime switch /design-app/<stage>/billing/export-watermark-enabled), this is false for every tier; once it is on, it is true for the Free tier and false for paid plans. An operator override on the subscription (entitlementOverrides.exportWatermarkRequired) wins over both.
    Organization:
      type: object
      properties:
        organizationId:
          type: string
          description: Unique identifier for the organization
        name:
          type: string
          description: Name of the organization
        stripeCustomerId:
          type: string
          description: Stripe customer ID
        createdAt:
          type: string
          format: date-time
          description: Timestamp of when the organization was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of the last update to organization
    User:
      type: object
      properties:
        userId:
          type: string
          description: Unique identifier for the user
        email:
          type: string
          description: Email of the user
        firstName:
          type: string
          description: First name of the user
        lastName:
          type: string
          description: Last name of the user
        companyName:
          type: string
          description: Optional company name (app metadata, not auth)
        profilePictureUrl:
          type: string
          description: Profile image URL (e.g. from federated IdP), synced on login
        stripeCustomerId:
          type: string
          description: Stripe customer ID
        createdAt:
          type: string
          format: date-time
          description: Timestamp of when the user was created
        updatedAt:
          type: string
          format: date-time
          description: Timestamp of the last update to user
        welcomeEmailSent:
          type: boolean
          description: Whether the welcome email has been sent
          deprecated: true
        welcomeEmailStatus:
          type: string
          enum:
          - SENT
          - NOT_SENT
          - IN_PROGRESS
          description: Status of the welcome email
        welcomeEmailSentAt:
          type: string
          format: date-time
          description: When the consumer welcome email was actually sent. Server-written only, set by a real send (never by a client update, and not for federated users, who are created with welcomeEmailStatus SENT without an email). Absent for accounts created before Sep 27, 2026.
          readOnly: true
        tooltipFlowIdsViewed:
          type: array
          items:
            type: string
          description: Id of all tooltip flows marked as viewed
        activeWorkspaceId:
          type: string
          format: uuid
          description: Current workspace context (multi-tenancy); set via PUT /users/{userId}/active-workspace
        allowedWorkspaces:
          type: integer
          minimum: 1
          description: 'Ops-only override (DynamoDB): max workspaces this user may own via POST /users/{userId}/workspaces. Omitted on normal users; overrides the stage default (typically 3). Not settable via public PUT /users.'
        marketingConsent:
          $ref: '#/components/schemas/MarketingConsentReceipt'
        marketingConsentPromptedAt:
          type: string
          format: date-time
          description: Set when the one-time consent prompt was shown and closed without an answer. Suppresses further prompting without recording a choice the user never made. Mutually exclusive with marketingConsent. Set via PUT /users/{userId}/marketing-consent.
        signUpPending:
          type: boolean
          enum:
          - true
          description: Present only while an account is still going through sign-up and has not resolved the marketing consent ask. Written by account creation, cleared by the first consent write, and absent on every row created before it was introduced. Not settable via any API.
  securitySchemes:
    cognitoUserAuth:
      type: oauth2
      description: Cognito authorization code flow for users
      flows:
        implicit:
          authorizationUrl: https://auth.app.blng.ai/oauth2/authorize
          scopes:
            email: email
            profile: profile
            openid: openid
            aws.cognito.signin.user.admin: aws.cognito.signin.user.admin
    machineBearerToken:
      type: http
      description: 'Cognito authorization code flow for billing token, request token with command like `curl -X POST https://auth.app.blng.ai/oauth2/token -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&client_id=7arq76lejqmgq3qc556vr7rupn&client_secret=CLIENT_SECRET&scope=blng/billing"`

        '
      scheme: bearer
      bearerFormat: JWT Access Token
x-provenance:
  method: harvested
  publisher: Blng
  source: https://users.blng.ai/swagger.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)