Baserow User sources API

openapi: 3.0.3
info:
  title: Baserow API spec Admin User sources API
  version: 2.2.2
  description: 'For more information about our REST API, please visit [this page](https://baserow.io/docs/apis%2Frest-api).


    For more information about our deprecation policy, please visit [this page](https://baserow.io/docs/apis%2Fdeprecations).'
  contact:
    url: https://baserow.io/contact
  license:
    name: MIT
    url: https://github.com/baserow/baserow/blob/develop/LICENSE
tags:
- name: User sources
paths:
  /api/application/{application_id}/list-user-source-users/:
    get:
      operationId: list_application_user_source_users
      description: List per user sources the first 5 users available.
      parameters:
      - in: path
        name: application_id
        schema:
          type: integer
        description: The application we want the users for.
        required: true
      tags:
      - User sources
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersPerUserSource'
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_APPLICATION_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/application/{application_id}/user-sources/:
    get:
      operationId: list_application_user_sources
      description: Lists all the user_sources of the application related to the provided parameter if the user has access to the related application's workspace. If the workspace is related to a template, then this endpoint will be publicly accessible.
      parameters:
      - in: path
        name: application_id
        schema:
          type: integer
        description: Returns only the user_sources of the application related to the provided Id.
        required: true
      tags:
      - User sources
      security:
      - UserSource JWT: []
      - JWT: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User_SourceUserSource'
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_APPLICATION_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
    post:
      operationId: create_application_user_source
      description: Creates a new user_source
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: path
        name: application_id
        schema:
          type: integer
        description: Creates an user_source for the application related to the provided value.
        required: true
      tags:
      - User sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User_SourceCreateUserSource'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/User_SourceCreateUserSource'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/User_SourceCreateUserSource'
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User_SourceUserSource'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_REQUEST_BODY_VALIDATION
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_APPLICATION_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/user-source-auth-refresh/:
    post:
      operationId: user_source_token_refresh
      description: Generate a new access_token that can be used to continue operating on Baserow with a user source user starting from a valid refresh token.
      tags:
      - User sources
      security:
      - JWT: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: '''access_token'' can be used to authorize for other endpoints that require authorization. This token will be valid for 10 minutes.'
          description: ''
        '401':
          content:
            application/json:
              schema:
                description: The JWT refresh token is invalid or expired.
          description: ''
  /api/user-source-token-blacklist/:
    post:
      operationId: user_source_token_blacklist
      description: Blacklists the provided user source token. This can be used the sign the user off.
      tags:
      - User sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenBlacklist'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenBlacklist'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TokenBlacklist'
        required: true
      responses:
        '204':
          description: No response body
        '401':
          content:
            application/json:
              schema:
                description: The JWT refresh token is invalid or expired.
          description: ''
  /api/user-source/{user_source_id}/:
    patch:
      operationId: update_application_user_source
      description: Updates an existing user_source.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: path
        name: user_source_id
        schema:
          type: integer
        description: The id of the user_source
        required: true
      tags:
      - User sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedUser_SourceUpdateUserSource'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedUser_SourceUpdateUserSource'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedUser_SourceUpdateUserSource'
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User_SourceUserSource'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_REQUEST_BODY_VALIDATION
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_SOURCE_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
    delete:
      operationId: delete_application_user_source
      description: Deletes the user_source related by the given id.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: path
        name: user_source_id
        schema:
          type: integer
        description: The id of the user_source
        required: true
      tags:
      - User sources
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '204':
          description: No response body
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_REQUEST_BODY_VALIDATION
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_SOURCE_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/user-source/{user_source_id}/force-token-auth:
    post:
      operationId: user_source_force_token_auth
      description: Force authenticates an existing user based on their ID. If successful, an access token and a refresh token will be returned.
      parameters:
      - in: path
        name: user_source_id
        schema:
          type: integer
        description: The user source to use to authenticate the user.
        required: true
      tags:
      - User sources
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: '''access_token'' can be used to authorize for other endpoints that require authorization. This token will be valid for 10 minutes.'
                  refresh_token:
                    type: string
                    description: '''refresh_token'' can be used to get a new valid ''access_token''. This token will be valid for 168 hours.'
          description: ''
        '401':
          content:
            application/json:
              schema:
                description: An active user with the provided ID could not be found.
          description: ''
  /api/user-source/{user_source_id}/move/:
    patch:
      operationId: move_application_user_source
      description: Moves the user_source in the application before another user_source or at the end of the application if no before user_source is given. The user_sources must belong to the same application.
      parameters:
      - in: header
        name: ClientSessionId
        schema:
          type: string
          format: uuid
        description: An optional header that marks the action performed by this request as having occurred in a particular client session. Then using the undo/redo endpoints with the same ClientSessionId header this action can be undone/redone.
      - in: path
        name: user_source_id
        schema:
          type: integer
        description: The id of the user_source to move
        required: true
      tags:
      - User sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedMoveUserSource'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedMoveUserSource'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedMoveUserSource'
      security:
      - UserSource JWT: []
      - JWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User_SourceUserSource'
          description: ''
        '400':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_REQUEST_BODY_VALIDATION
                    - ERROR_USER_SOURCE_NOT_IN_SAME_APPLICATION
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
        '404':
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Machine readable error indicating what went wrong.
                    enum:
                    - ERROR_USER_SOURCE_DOES_NOT_EXIST
                  detail:
                    oneOf:
                    - type: string
                      format: string
                      description: Human readable details about what went wrong.
                    - type: object
                      format: object
                      description: Machine readable object about what went wrong.
          description: ''
  /api/user-source/{user_source_id}/token-auth:
    post:
      operationId: user_source_token_auth
      description: Authenticates an existing user against a user source based on their credentials. If successful, an access token and a refresh token will be returned.
      parameters:
      - in: path
        name: user_source_id
        schema:
          type: integer
        description: The id of the user_source to move
        required: true
      tags:
      - User sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TokenObtainPair'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenObtainPair'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/TokenObtainPair'
        required: true
      security:
      - JWT: []
      - {}
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    description: '''access_token'' can be used to authorize for other endpoints that require authorization. This token will be valid for 10 minutes.'
                  refresh_token:
                    type: string
                    description: '''refresh_token'' can be used to get a new valid ''access_token''. This token will be valid for 168 hours.'
          description: ''
        '401':
          content:
            application/json:
              schema:
                description: An active user with the provided email and password could not be found.
          description: ''
  /api/user-source/{user_source_uid}/sso/oauth2/openid_connect/callback/:
    get:
      operationId: app_auth_oidc_login_callback
      description: Processes callback from OAuth2 provider and logs the user in if successful.
      parameters:
      - in: query
        name: code
        schema:
          type: string
        description: The code returned by the IDP.
      - in: query
        name: state
        schema:
          type: string
        description: The oauth state returned by the IDP.
      - in: path
        name: user_source_uid
        schema:
          type: integer
        description: The uid of the user source for which to process the callback.
        required: true
      tags:
      - User sources
      responses:
        '302':
          description: No response body
  /api/user-source/{user_source_uid}/sso/oauth2/openid_connect/login/:
    get:
      operationId: app_auth_oidc_login_redirect
      description: Redirects to the OAuth2 provider's authentication URL based on the provided user source uid and issuer.
      parameters:
      - in: query
        name: iss
        schema:
          type: string
        description: The issuer of the authentication.
      - in: query
        name: original
        schema:
          type: string
        description: The URL that the user wants to access.
      - in: path
        name: user_source_uid
        schema:
          type: integer
        description: The uid of the user source to use for authentication.
        required: true
      tags:
      - User sources
      responses:
        '302':
          description: No response body
  /api/user-source/{user_source_uid}/sso/saml/login/:
    get:
      operationId: app_auth_provider_saml_sp_login
      description: This is the endpoint that is called when the user wants to initiate a SSO SAML login from Baserow (the service provider). The user will be redirected to the SAML identity provider (IdP) where the user can authenticate. Once logged in in the IdP, the user will be redirected back to the assertion consumer service endpoint (ACS) where the SAML response will be validated and a new JWT session token will be provided to work with Baserow APIs.
      parameters:
      - in: query
        name: email
        schema:
          type: string
        description: The email address of the user that want to sign in using SAML.
      - in: query
        name: original
        schema:
          type: string
        description: The url to which the user should be redirected after a successful login or sign up.
      - in: path
        name: user_source_uid
        schema:
          type: string
        required: true
      tags:
      - User sources
      responses:
        '302':
          description: No response body
  /api/user-source/sso/saml/acs/:
    post:
      operationId: auth_provider_saml_acs_url_2
      description: Complete the SAML authentication flow by validating the SAML response. Sign in the user if already exists in the user source or create a new one otherwise.Once authenticated, the user will be redirected to the original URL they were trying to access. If the response is invalid, the user will be redirected to an error page with a specific error message.
      tags:
      - User sources
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommonSAMLResponse'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CommonSAMLResponse'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CommonSAMLResponse'
        required: true
      responses:
        '302':
          description: No response body
components:
  schemas:
    SamlAppAuthProviderModelAppAuthProvider:
      type: object
      description: Basic app_auth_provider serializer mostly for returned values.
      properties:
        type:
          type: string
          readOnly: true
          description: The type of the app_auth_provider.
        id:
          type: integer
          readOnly: true
        domain:
          type: string
          nullable: true
          description: The email domain registered with this provider.
          maxLength: 255
        metadata:
          type: string
          description: The SAML metadata XML provided by the IdP.
        is_verified:
          type: boolean
          readOnly: true
          description: Whether or not a user sign in correctly with this SAML provider.
        email_attr_key:
          type: string
          description: The key in the SAML response that contains the email address of the user.
        first_name_attr_key:
          type: string
          description: The key in the SAML response that contains the first name of the user.
        last_name_attr_key:
          type: string
          description: The key in the SAML response that contains the last name of the user. If this is not set, the first name attr will be used as full name.
      required:
      - id
      - is_verified
      - metadata
      - type
    TokenBlacklist:
      type: object
      properties:
        refresh:
          type: string
          writeOnly: true
      required:
      - refresh
    UsersPerUserSource:
      type: object
      description: The response of the list user source users endpoint.
      properties:
        users_per_user_sources:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/UserSourceUser'
          description: An object keyed by the id of the user source and the value being the list of users for this user source.
      required:
      - users_per_user_sources
    OpenIdConnectAppAuthProviderModelBaseAppAuthProvider:
      type: object
      description: 'This serializer allow to set the type of an app_auth_provider and the

        app_auth_provider id before which we want to insert the new app_auth_provider.'
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/Type6b3Enum'
          description: 'The type of the app_auth_provider.


            * `local_baserow_password` - local_baserow_password

            * `saml` - saml

            * `openid_connect` - openid_connect'
        user_source_id:
          type: integer
          readOnly: true
        domain:
          type: string
          nullable: true
          description: The email domain registered with this provider.
        name:
          type: string
          maxLength: 255
        base_url:
          type: string
          description: The provider base url.
        client_id:
          type: string
          description: App ID, or consumer key
          maxLength: 191
        secret:
          type: string
          description: API secret, client secret, or consumer secret
          maxLength: 191
        use_id_token:
          type: boolean
          description: Whether to use the id_token instead of user_info endpoint to get user data
        email_attr_key:
          type: string
          description: The name of the claim that contains the email address of the user.
          maxLength: 32
        first_name_attr_key:
          type: string
          description: The key in the OIDC response that contains the first name of the user.
          maxLength: 32
        last_name_attr_key:
          type: string
          description: The key in the OIDC response that contains the last name of the user. If empty in response, first name will be used.
          maxLength: 32
      required:
      - base_url
      - client_id
      - name
      - secret
      - type
      - user_source_id
    User_SourceCreateUserSource:
      oneOf:
      - $ref: '#/components/schemas/LocalBaserowUserSourceCreateUserSource'
      discriminator:
        propertyName: type
        mapping:
          local_baserow: '#/components/schemas/LocalBaserowUserSourceCreateUserSource'
    OpenIdConnectAppAuthProviderModelAppAuthProvider:
      type: object
      description: Basic app_auth_provider serializer mostly for returned values.
      properties:
        type:
          type: string
          readOnly: true
          description: The type of the app_auth_provider.
        id:
          type: integer
          readOnly: true
        domain:
          type: string
          nullable: true
          description: The email domain registered with this provider.
          maxLength: 255
        name:
          type: string
          maxLength: 255
        base_url:
          type: string
          description: The provider base url.
        client_id:
          type: string
          description: App ID, or consumer key
          maxLength: 191
        secret:
          type: string
          description: API secret, client secret, or consumer secret
          maxLength: 191
        use_id_token:
          type: boolean
          description: Whether to use the id_token instead of user_info endpoint to get user data
        email_attr_key:
          type: string
          description: The name of the claim that contains the email address of the user.
          maxLength: 32
        first_name_attr_key:
          type: string
          description: The key in the OIDC response that contains the first name of the user.
          maxLength: 32
        last_name_attr_key:
          type: string
          description: The key in the OIDC response that contains the last name of the user. If empty in response, first name will be used.
          maxLength: 32
      required:
      - base_url
      - client_id
      - id
      - name
      - secret
      - type
    App_Auth_ProviderBaseAppAuthProvider:
      oneOf:
      - $ref: '#/components/schemas/LocalBaserowPasswordAppAuthProviderBaseAppAuthProvider'
      - $ref: '#/components/schemas/SamlAppAuthProviderModelBaseAppAuthProvider'
      - $ref: '#/components/schemas/OpenIdConnectAppAuthProviderModelBaseAppAuthProvider'
      discriminator:
        propertyName: type
        mapping:
          local_baserow_password: '#/components/schemas/LocalBaserowPasswordAppAuthProviderBaseAppAuthProvider'
          saml: '#/components/schemas/SamlAppAuthProviderModelBaseAppAuthProvider'
          openid_connect: '#/components/schemas/OpenIdConnectAppAuthProviderModelBaseAppAuthProvider'
    LocalBaserowPasswordAppAuthProviderBaseAppAuthProvider:
      type: object
      description: 'This serializer allow to set the type of an app_auth_provider and the

        app_auth_provider id before which we want to insert the new app_auth_provider.'
      properties:
        type:
          allOf:
          - $ref: '#/components/schemas/Type6b3Enum'
          description: 'The type of the app_auth_provider.


            * `local_baserow_password` - local_baserow_password

            * `saml` - saml

            * `openid_connect` - openid_connect'
        user_source_id:
          type: integer
          readOnly: true
        domain:
          type: string
          nullable: true
          description: The email domain registered with this provider.
        password_field_id:
          type: integer
          nullable: true
          description: The id of the field to use as password for the user account.
      required:
      - type
      - user_source_id
    PatchedMoveUserSource:
      type: object
      description: Serializer used when moving a user source.
      properties:
        before_id:
          type: integer
          nullable: true
          description: If provided, the user_source is moved before the user_source with this Id. Otherwise the user_source is placed at the end of the page.
    UserSourceUser:
      type: object
      description: A serializer used to serialize a UserSourceUser object.
      properties:
        id:
          type: integer
        username:
          type: string
        email:
          type: string
          format: email
        user_source_id:
          type: integer
        role:
          type: string
      required:
      - email
      - id
      - role
      - user_source_id
      - username
    Type6b3Enum:
      enum:
      - local_baserow_password
      - saml
      - openid_connect
      type: string
      description: '* `local_baserow_password` - local_baserow_password

        * `saml` - saml

        * `openid_connect` - openid_connect'
    CommonSAMLResponse:
      type: object
      properties:
        SAMLResponse:
          type: string
          description: The encoded SAML response from the IdP.
        RelayState:
          type: string
          description: The frontend URL where redirect the authenticated user.
      required:
      - RelayState
      - SAMLResponse
    User_SourceUserSource:
      oneOf:
      - $ref: '#/components/schemas/LocalBaserowUserSourceUserSource'
      discriminator:
        propertyName: type
        mapping:
          loc

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/baserow/refs/heads/main/openapi/baserow-user-sources-api-openapi.yml