openapi: 3.0.1
info:
  title: Softr Databases Users API
  description: Public REST APIs for Softr - the no-code app and client-portal builder. Covers the Users Management API (studio-api.softr.io) for managing the end users of a published Softr app, and the Softr Database API (tables-api.softr.io) for reading and writing records in the native Softr Database. Both APIs authenticate with a Softr-Api-Key header; the Users Management API additionally requires a Softr-Domain header identifying the target app.
  termsOfService: https://www.softr.io/terms
  contact:
    name: Softr Support
    url: https://docs.softr.io
  version: '1.0'
servers:
- url: https://studio-api.softr.io/v1/api
  description: Users Management API
- url: https://tables-api.softr.io/api/v1
  description: Softr Database API
security:
- SoftrApiKey: []
tags:
- name: Users
  description: Manage end users of a published Softr app.
paths:
  /users:
    post:
      operationId: createUser
      tags:
      - Users
      summary: Create a user
      description: Creates a user inside the specified Softr app. If no password is supplied one is generated automatically. The app must be published and the Softr-Domain header must identify the app.
      parameters:
      - $ref: '#/components/parameters/SoftrDomain'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '200':
          description: User created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{email}:
    delete:
      operationId: deleteUser
      tags:
      - Users
      summary: Delete a user
      description: Removes an existing user from the Softr app. This action is irreversible.
      parameters:
      - $ref: '#/components/parameters/SoftrDomain'
      - $ref: '#/components/parameters/Email'
      responses:
        '200':
          description: User deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{email}/activate:
    post:
      operationId: activateUser
      tags:
      - Users
      summary: Activate a user
      description: Reactivates a previously deactivated user in the specified Softr app.
      parameters:
      - $ref: '#/components/parameters/SoftrDomain'
      - $ref: '#/components/parameters/Email'
      responses:
        '200':
          description: User activated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{email}/deactivate:
    post:
      operationId: deactivateUser
      tags:
      - Users
      summary: Deactivate a user
      description: Deactivates a user, disabling login while preserving the user record.
      parameters:
      - $ref: '#/components/parameters/SoftrDomain'
      - $ref: '#/components/parameters/Email'
      responses:
        '200':
          description: User deactivated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{email}/invite:
    post:
      operationId: inviteUser
      tags:
      - Users
      summary: Invite a user
      description: Sends an invitation email to an existing user of the Softr app and sets the user status to Invited. The app must be published for invitations to be sent.
      parameters:
      - $ref: '#/components/parameters/SoftrDomain'
      - $ref: '#/components/parameters/Email'
      responses:
        '200':
          description: Invitation sent.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/magic-link/generate/{email}:
    post:
      operationId: generateMagicLink
      tags:
      - Users
      summary: Generate a Magic Link
      description: Generates a Magic Link granting passwordless access for the specified user.
      parameters:
      - $ref: '#/components/parameters/SoftrDomain'
      - $ref: '#/components/parameters/Email'
      responses:
        '200':
          description: Magic Link generated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MagicLink'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/sync:
    post:
      operationId: syncUsers
      tags:
      - Users
      summary: Sync users
      description: Syncs a single user, a group of users, or all users of the Softr app.
      parameters:
      - $ref: '#/components/parameters/SoftrDomain'
      responses:
        '200':
          description: Sync started.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    MagicLink:
      type: object
      properties:
        magic_link:
          type: string
          format: uri
    User:
      type: object
      properties:
        full_name:
          type: string
        email:
          type: string
          format: email
        status:
          type: string
          example: Active
    CreateUserRequest:
      type: object
      required:
      - full_name
      - email
      properties:
        full_name:
          type: string
          example: John Richardson
        email:
          type: string
          format: email
          example: johnr@gmail.com
        password:
          type: string
          description: Optional. Auto-generated if omitted.
          example: '12345678'
        generate_magic_link:
          type: boolean
          description: Whether to generate a Magic Link for the new user.
          example: true
  parameters:
    SoftrDomain:
      name: Softr-Domain
      in: header
      required: true
      description: The domain or subdomain of the target Softr app (Users Management API only).
      schema:
        type: string
    Email:
      name: email
      in: path
      required: true
      description: The email address identifying the user.
      schema:
        type: string
        format: email
  responses:
    Unauthorized:
      description: Missing or invalid Softr-Api-Key (or Softr-Domain).
  securitySchemes:
    SoftrApiKey:
      type: apiKey
      in: header
      name: Softr-Api-Key
      description: Personal access token generated from the Softr workspace settings.