openapi: 3.0.1
info:
  title: Nile ReST API
  description: Making SaaS chill.
  contact:
    email: support@thenile.dev
  version: 0.1.0-6def472
servers:
- url: https://api.thenile.dev
paths:
  /workspaces/{workspaceSlug}/databases/{databaseName}/credentials:
    get:
      tags:
      - databases
      summary: List credentials
      description: Lists credentials for a database.
      operationId: listCredentials
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: List of credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Credential'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - databases
      summary: Create a credential
      description: "Generates a new secure credential for a database. The generated\
        \ password is returned in the response, and is the only time the password\
        \ is available in plaintext. No request body is required."
      operationId: createCredential
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Credential created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCredentialResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/configure:
    get:
      operationId: getDatabase
      parameters:
      - name: databaseName
        in: query
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/DatabaseUser'
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDatabaseResponse'
  /workspaces/{workspaceSlug}/databases:
    get:
      tags:
      - databases
      summary: List databases
      description: Lists all of the databases in a workspace.
      operationId: listDatabases
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: A list of databases
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetDatabaseResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Workspace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - databases
      summary: Create a database
      description: "Creates a database record in the control plane and triggers creation\
        \ in the target region. Database names must be less than 64 characters, and\
        \ unique within a workspace. Names may contain letters (lower or uppercase),\
        \ numbers, and underscores."
      operationId: createDatabase
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/CreateDatabaseRequest'
        required: true
      responses:
        "201":
          description: Database created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDatabaseResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Workspace not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "409":
          description: Database already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/invites:
    get:
      tags:
      - developers
      - workspaces
      summary: List developer invites
      description: Lists all developer invites in a workspace
      operationId: listDeveloperInvites
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: verificationState
        in: query
        schema:
          $ref: '#/components/schemas/EmailVerificationStateFilter'
      responses:
        "200":
          description: List of invites
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DeveloperInvite'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - developers
      - workspaces
      summary: Invite a developer to a workspace
      description: Sends an email to another developer with a link that allows them
        to join the workspace.
      operationId: createDeveloperInvite
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: The email address of the developer to invite.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInviteRequest'
            examples:
              Create Invite Request:
                summary: Creates an invite and sends an email to the specified recipient
                description: Create Invite Request
        required: true
      responses:
        "201":
          description: Invite created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeveloperInvite'
        "202":
          description: Pending email delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "401":
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/invites/{inviteId}:
    delete:
      tags:
      - developers
      - workspaces
      summary: Deletes a previously issued invite
      operationId: deleteDeveloperInvite
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: inviteId
        in: path
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Invite deleted
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Invite not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /developers/oidc/{providerName}/callback:
    get:
      tags:
      - developers
      summary: Handle OIDC callback for a developer
      description: Handles the callback from a known OIDC provider for developer login
        (This is the URL provided to the OIDC provider as the callback URL.)
      operationId: handleDeveloperOIDCCallback
      parameters:
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      - name: code
        in: query
        description: The unique code that may be exchanged for an access and/or id
          token with the OIDC provider
        required: true
        schema:
          type: string
      - name: state
        in: query
        description: The state parameter generated by Nile for the authentication
          attempt
        required: true
        schema:
          type: string
      responses:
        "200":
          description: An intermediate page that redirects to the Nile Console
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/OIDCFormPostView'
  /developers/me:
    get:
      tags:
      - users
      summary: Identify the developer
      description: Returns information about the developer associated with the token
        provided
      operationId: identifyDeveloper
      responses:
        "200":
          description: Developer found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Developer'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Developer not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /developers/oidc/{providerName}/login:
    get:
      tags:
      - developers
      summary: Initiate OIDC developer login
      description: Initiates the OIDC login flow for a known authentication provider.
      operationId: loginDeveloperWithOIDC
      parameters:
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      - name: inviteCode
        in: query
        schema:
          type: string
      responses:
        "302":
          description: Redirect to the provider's login page
        "404":
          description: Unknown OIDC provider
  /workspaces/{workspaceSlug}/regions:
    get:
      tags:
      - databases
      summary: List available regions
      operationId: listRegions
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Available regions
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  enum:
                  - AWS_US_WEST_2
                  - AWS_EU_CENTRAL_1
      security:
      - jwtBearerAuth: []
  /workspaces:
    get:
      tags:
      - workspaces
      summary: List workspaces
      description: Lists workspaces available to the authenticated developer.
      operationId: list
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/Developer'
        required: true
      responses:
        "200":
          description: List of workspaces
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Workspace'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - workspaces
      summary: Create a workspace
      description: Creates a workspace for the authenticated developer. A workspace
        slug is generated from the workspace name and used as the workspace identifier.
        Workspace slugs must be globally unique.
      operationId: create
      requestBody:
        description: A wrapper for the workspace name.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkspaceRequest'
            examples:
              Create Workspace Request:
                summary: Creates a named workspace
                description: Create Workspace Request
                value:
                  name: My Unique Workspace
      responses:
        "201":
          description: Created workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "409":
          description: Workspace with the same name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/developers:
    get:
      operationId: listWorkspaceDevelopers
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      responses:
        default:
          description: default response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Developer'
  /workspaces/{workspaceSlug}/databases/{databaseName}/auth/oidc/providers:
    get:
      tags:
      - authentication
      summary: List OIDC providers
      description: Lists all OIDC providers registered in the database.
      operationId: globalListOIDCProviders
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: List of OIDC providers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OIDCProvider'
    post:
      tags:
      - authentication
      summary: Create OIDC provider
      description: "Creates an OIDC provider with the database. During creation, the\
        \ well-known configuration is loaded from the `configUrl` and stored in the\
        \ database. \nGoogle and Okta are supported out of the box. Use this endpoint\
        \ to register other OIDC providers."
      operationId: globalCreateOIDCProvider
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: "The configuration for a new OIDC provider. A provider must have\
          \ a unique name and a valid `configUrl` pointing to the well-known OIDC\
          \ configuration. If the provider is enabled, the `redirectUrl` back to your\
          \ application must be specified. (Without the `redirectUrl`, Nile cannot\
          \ resolve authentication attempts.)"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OIDCProvider'
            examples:
              Create Social Provider:
                summary: Registers a new social login provider
                description: Create Social Provider
                value:
                  name: Some Social Host
                  authType: SOCIAL
                  enabled: true
                  configUrl: https://some-social-host.com/.well-known/openid-configuration
                  redirectUrl: https://myapp.com/auth/handler
              Create SSO Provider:
                summary: Registers a new SSO provider
                description: Create SSO Provider
                value:
                  name: Some SSO Host
                  authType: SSO
                  enabled: true
                  configUrl: https://some-sso-host.com/.well-known/openid-configuration
                  redirectUrl: https://myapp.com/auth/handler
      responses:
        "200":
          description: Updated OIDC provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCProvider'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "409":
          description: OIDC provider already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "502":
          description: OIDC provider configuration does not match host URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/auth/oidc/providers/{providerName}:
    get:
      tags:
      - authentication
      summary: Get an OIDC provider
      description: "Gets an OIDC provider by name. If the well-known config for the\
        \ provider is determined to  have expired, the latest config is fetched and\
        \ retained, ensuring that the provider information returned is always current."
      operationId: globalGetOIDCProvider
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OIDC provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCProvider'
        "404":
          description: OIDC provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
    put:
      tags:
      - authentication
      summary: Update OIDC provider
      description: "Updates a named OIDC provider. During an update, the well-known\
        \ configuration is refreshed."
      operationId: globalUpdateOIDCProvider
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: "The new configuration values for an existing OIDC provider.\
          \ (The `name` may not be modified.) If the provider is enabled, the `redirectUrl`\
          \ back to your application must be specified. (Without the `redirectUrl`,\
          \ Nile cannot resolve authentication attempts.)"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OIDCProvider'
            examples:
              Update Social Provider:
                summary: Updates the existing social provider configuration
                description: Update Social Provider
                value:
                  name: Some Social Host
                  authType: SOCIAL
                  enabled: true
                  configUrl: https://some-social-host.com/.well-known/openid-configuration
                  redirectUrl: https://myapp.com/auth/handler
              Update SSO Provider:
                summary: Updates the existing SSO provider configuration
                description: Update SSO Provider
                value:
                  name: Some SSO Host
                  authType: SSO
                  enabled: true
                  configUrl: https://some-sso-host.com/.well-known/openid-configuration
                  redirectUrl: https://myapp.com/auth/handler
      responses:
        "200":
          description: Updated OIDC provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCProvider'
        "400":
          description: OIDC provider name mismatch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: OIDC provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/auth/oidc/relyingparties:
    get:
      tags:
      - authentication
      summary: List relying parties
      description: Lists all OIDC relying parties in the database.
      operationId: globalListRelyingParties
      responses:
        "200":
          description: List of relying parties
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OIDCRelyingParty'
      security:
      - jwtBearerAuth: []
    put:
      tags:
      - authentication
      summary: Update relying party
      description: "Updates an OIDC relying party. The `clientId`, `clientSecret`\
        \ and `enabled` properties may be modified."
      operationId: globalUpdateRelyingParty
      requestBody:
        description: "Configuration details for an existing OIDC relying party. The\
          \ `clientId`, `clientSecret` and `enabled` properties may be modified."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OIDCRelyingParty'
            examples:
              Create Relying Party Request:
                summary: Registers a relying party for an OIDC provider
                description: Create Relying Party Request
                value:
                  provider: GOOGLE
                  clientId: 0oa1b2c3d4e5f6g7h8i9j
                  clientSecret: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
                  enabled: true
      responses:
        "200":
          description: Relying party updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCRelyingParty'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Relying party not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - authentication
      summary: Create relying party
      description: Creates a relying party associated with a known OIDC provider.
      operationId: globalCreateRelyingParty
      requestBody:
        description: Configuration details for an OIDC relying party that relies on  a
          registered OIDC provider. This should include the client ID and secret for
          the relying party.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OIDCRelyingParty'
            examples:
              Create Relying Party Request:
                summary: Registers a relying party for an OIDC provider
                description: Create Relying Party Request
                value:
                  provider: GOOGLE
                  clientId: 0oa1b2c3d4e5f6g7h8i9j
                  clientSecret: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
                  enabled: true
      responses:
        "201":
          description: Relying party created successfully
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/auth/oidc/relyingparties/{relyingPartyId}:
    get:
      tags:
      - authentication
      summary: Get a relying party
      description: Get an OIDC relying party by its identifier.
      operationId: globalGetRelyingParty
      parameters:
      - name: relyingPartyId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: The relying party
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCRelyingParty'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Relying party not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/tenants/auth/oidc/locations:
    get:
      tags:
      - authentication
      summary: List SSO URLs
      description: Lists all SSO login URLs for all tenants in the database. The `provider`
        and `email` query parameters can be used to filter the results.
      operationId: globalListTenantSSOLocations
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: provider
        in: query
        schema:
          type: string
      - name: email
        in: query
        schema:
          type: string
      responses:
        "200":
          description: List of authorization URLs
          content:
            application/json:
              schema:
                type: string
                format: uri
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
  /workspaces/{workspaceSlug}/databases/{databaseName}/tenants/auth/oidc/providers:
    get:
      tags:
      - authentication
      summary: List registered SSO providers
      description: Lists all SSO providers registered for all tenants. The `provider`
        and `email` query parameters can be used to filter the results.
      operationId: globalListTenantSSOProviders
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: provider
        in: query
        schema:
          type: string
      - name: email
        in: query
        schema:
          type: string
      responses:
        "200":
          description: List of registered providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSSORegistration'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/tenants/{tenantId}/auth/oidc/providers/{providerName}:
    get:
      tags:
      - authentication
      summary: Get SSO registration
      description: Gets the configuration for a single sign-on provider registered
        for a tenant.
      operationId: globalGetTenantSSORegistration
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: The registered configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSSORegistration'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    put:
      tags:
      - authentication
      summary: Update tenant SSO provider
      description: Updates a single sign-on provider configuration for a specific
        tenant.
      operationId: globalUpdateTenantSSOProvider
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: "Configuration details for a single sign-on provider. Any values\
          \ provided will overwrite existing values. If a value is not provided, the\
          \ existing value will be retained."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantSSORegistration'
            examples:
              Partial Configuration:
                description: Partial Configuration
                value: |
                  {
                    "clientId": "0oa1b2c3d4e5f6g7h8i9j",
                    "clientSecret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
                  }
      responses:
        "200":
          description: Updated configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSSORegistration'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "502":
          description: Provider configuration does not match host URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - authentication
      summary: Register tenant SSO provider
      description: Registers a single sign-on provider configuration for a specific
        tenant.
      operationId: globalRegisterTenantSSOProvider
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: |-
          Configuration details for a single sign-on provider, including the email domains that should be associated with the provider.
          Note: the email domains you provide should usually correspond to the domains configured with the provider.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantSSORegistration'
            examples:
              Sample Okta Configuration:
                description: Sample Okta Configuration
                value:
                  configUrl: https://dev-123456.okta.com/.well-known/openid-configuration
                  clientId: 0oa1b2c3d4e5f6g7h8i9j
                  clientSecret: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
                  emailDomains:
                  - mycompany.com
                  - anothercompany.com
                  enabled: true
      responses:
        "200":
          description: Registered configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSSORegistration'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "409":
          description: Provider already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "502":
          description: Provider configuration does not match host URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/tenants/{tenantId}/auth/oidc/callback:
    get:
      tags:
      - users
      summary: Handle OIDC callback for a tenant user
      description: Handles the callback from an OIDC provider for a specific tenant.
        (This is the URL provided to the OIDC provider as the callback URL.)
      operationId: globalHandleTenantOIDCCallback
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: code
        in: query
        required: true
        schema:
          type: string
      - name: state
        in: query
        required: true
        schema:
          type: string
      responses:
        "200":
          description: A form post to the configured redirect URL
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/OIDCFormPostView'
  /workspaces/{workspaceSlug}/databases/{databaseName}/tenants/{tenantId}/auth/oidc/providers:
    get:
      tags:
      - authentication
      summary: List SSO registrations
      description: Lists all single sign-on provider configurations that are registered
        for a tenant.
      operationId: globalListTenantSSORegistrations
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: List of registered configurations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TenantSSORegistration'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/tenants/{tenantId}/auth/oidc/providers/{providerName}/login:
    get:
      tags:
      - authentication
      summary: Initiate OIDC login for a tenant
      description: Initiates the OIDC login flow for a registered authentication provider.
      operationId: globalLoginTenantProvider
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      responses:
        "302":
          description: Redirect to the provider's login page
        "404":
          description: Unknown OIDC provider
  /workspaces/{workspaceSlug}/databases/{databaseName}/tenants:
    get:
      summary: List tenants
      description: "Lists all tenants in a database. If a developer token is provided,\
        \ all tenants are listed. If a user token is provided, only tenants that the\
        \ user is a member of are listed."
      operationId: globalListTenants
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: List of tenants
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tenant'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - tenants
      summary: Create a tenant
      description: Creates a new tenant in a database.
      operationId: globalCreateTenant
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: A wrapper for the tenant name.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTenantRequest'
            examples:
              Create Tenant Request:
                summary: Creates a named tenant
                description: Create Tenant Request
                value:
                  name: My Sandbox
      responses:
        "201":
          description: Tenant created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Database not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/tenants/{tenantId}:
    get:
      tags:
      - tenants
      summary: Get a tenant
      description: Gets a tenant from a database.
      operationId: globalGetTenant
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: A Tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Tenant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    put:
      tags:
      - tenants
      summary: Update a tenant
      description: Updates a tenant. Only the tenant name may be updated.
      operationId: globalUpdateTenant
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: A wrapper for the tenant name.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTenantRequest'
            examples:
              Update Tenant Request:
                summary: Updates a tenant name
                description: Update Tenant Request
                value:
                  name: Customer One
      responses:
        "200":
          description: Tenant updated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tenant'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Tenant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    delete:
      tags:
      - tenants
      summary: Deletes a tenant.
      operationId: globalDeleteTenant
      parameters:
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Tenant deleted
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Tenant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/tenants/{tenantId}/users:
    get:
      tags:
      - users
      summary: List tenant users
      description: Lists users that are associated with the specified tenant.
      operationId: globalListTenantUsers
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Users found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - users
      summary: Create a user in a tenant
      description: Creates a new user and associates that user with the specified
        tenant.
      operationId: globalCreateTenantUser
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: |
          The email and password combination the user will use to authenticate.
          The `name` is optional; if provided it will be recorded in the `users` table.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBasicUserRequest'
            examples:
              Create User Request:
                summary: Creates a user with basic credentials
                description: Create User Request
                value:
                  email: a.user@somedomain.com
                  password: somepassword
                  name: A. User
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginUserResponse'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/tenants/{tenantId}/users/{userId}:
    get:
      tags:
      - users
      summary: Get a user in a tenant
      description: "Gets information about a user, but only if that user belongs to\
        \ the tenant specified. If the user does not belong to the tenant, this returns\
        \ 404 (Not Found)."
      operationId: globalGetTenantUser
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/tenants/{tenantId}/users/login:
    post:
      tags:
      - users
      summary: Login a user in a tenant
      description: "Authenticates a user, ensuring that the user is a member of the\
        \ tenant. If the user is not a member of the tenant, this returns 401 (Unauthorized)."
      operationId: globalLoginTenantUser
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: The email and password combination the user registered with.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              Login Request:
                description: Login Request
                value:
                  email: a.user@somedomain.com
                  password: somepassword
      responses:
        "200":
          description: User logged in successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginUserResponse'
        "401":
          description: User authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
  /workspaces/{workspaceSlug}/databases/{databaseName}/users:
    get:
      tags:
      - users
      summary: List database users
      description: Lists all users in the database
      operationId: globalListUsers
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Users found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - users
      summary: Create a new user
      description: Creates a new user using basic credentials—email address and password.
      operationId: globalCreateUser
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: |-
          The email and password combination the user will use to authenticate.
          The `name` is optional; if provided it will be recorded in the `users` table.
          The `newTenant` is optional; if provided, it is used as the name of a new tenant record associated with the newly created user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBasicUserRequest'
            examples:
              Create User Request:
                summary: Creates a user with basic credentials
                description: Create User Request
                value:
                  email: a.user@somedomain.com
                  password: somepassword
                  name: A. User
              Create User Request with Tenant:
                summary: Creates a user and a new tenant for that user
                description: Create User Request with Tenant
                value:
                  email: a.user@somedomain.com
                  password: somepassword
                  name: A. User
                  newTenant: My Sandbox
      responses:
        "201":
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginUserResponse'
  /workspaces/{workspaceSlug}/databases/{databaseName}/users/{userId}:
    get:
      tags:
      - users
      summary: Get a user
      description: Gets a user by id.
      operationId: globalGetUser
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    put:
      tags:
      - users
      summary: Update a user
      description: Updates user attributes by id.
      operationId: globalUpdateUser
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
        required: true
      responses:
        "200":
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    delete:
      tags:
      - users
      summary: Delete a user
      description: Deletes a user from the database
      operationId: globalDeleteUser
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        "204":
          description: User deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/users/oidc/callback:
    get:
      tags:
      - users
      summary: Handle OIDC callback for a user
      description: Handles the callback from an OIDC provider. (This is the URL provided
        to the OIDC provider as the callback URL.)
      operationId: globalHandleOIDCCallback
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: code
        in: query
        required: true
        schema:
          type: string
      - name: state
        in: query
        required: true
        schema:
          type: string
      responses:
        "200":
          description: A form post to the configured redirect URL
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/OIDCFormPostView'
  /workspaces/{workspaceSlug}/databases/{databaseName}/users/me:
    get:
      tags:
      - users
      summary: Identify the user
      description: Returns information about the user associated with the token provided
      operationId: globalIdentifyUser
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /workspaces/{workspaceSlug}/databases/{databaseName}/users/login:
    post:
      tags:
      - users
      summary: Login a user
      description: Login a user with email and password
      operationId: globalLoginUser
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: The email and password combination the user registered with.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              Login Request:
                description: Login Request
                value:
                  email: a.user@somedomain.com
                  password: somepassword
      responses:
        "200":
          description: User logged in successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginUserResponse'
        "401":
          description: User authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
  /workspaces/{workspaceSlug}/databases/{databaseName}/users/oidc/{providerName}/login:
    get:
      tags:
      - users
      summary: Initiate OIDC user login
      description: Initiates the OIDC login flow for a known authentication provider.
      operationId: globalLoginOIDCUser
      parameters:
      - name: workspaceSlug
        in: path
        required: true
        schema:
          type: string
      - name: databaseName
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      - name: newTenant
        in: query
        schema:
          type: string
      - name: nonce
        in: query
        schema:
          type: string
      responses:
        "302":
          description: Redirect to the provider's login page
        "404":
          description: Unknown OIDC provider
  /databases/{databaseId}:
    get:
      tags:
      - databases
      summary: (Internal) Get a logical database
      description: Gets details of a logical database from the data plane.
      operationId: internalGetLogicalDatabase
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Database details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogicalDatabase'
        "404":
          description: Database not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
  /databases/{databaseId}/status:
    get:
      tags:
      - databases
      summary: (Internal) Get database creation status
      description: Get the creation status of a specific database
      operationId: internalGetDatabaseStatus
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: The current status of the database
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GetDatabaseStatusResponse'
        "404":
          description: Database not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
  /databases/me:
    get:
      tags:
      - databases
      summary: Identify the principal
      description: Returns information about the principal associated with the token
        provided
      operationId: identifyPrincipal
      responses:
        "200":
          description: Principal identified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PrincipalResponse'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Principal not identified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/auth/oidc/providers:
    get:
      tags:
      - authentication
      summary: List OIDC providers
      description: Lists all OIDC providers registered in the database.
      operationId: listOIDCProviders
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: List of OIDC providers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OIDCProvider'
    post:
      tags:
      - authentication
      summary: Create OIDC provider
      description: "Creates an OIDC provider with the database. During creation, the\
        \ well-known configuration is loaded from the `configUrl` and stored in the\
        \ database. \nGoogle and Okta are supported out of the box. Use this endpoint\
        \ to register other OIDC providers."
      operationId: createOIDCProvider
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: "The configuration for a new OIDC provider. A provider must have\
          \ a unique name and a valid `configUrl` pointing to the well-known OIDC\
          \ configuration. If the provider is enabled, the `redirectUrl` back to your\
          \ application must be specified. (Without the `redirectUrl`, Nile cannot\
          \ resolve authentication attempts.)"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OIDCProvider'
            examples:
              Create Social Provider:
                summary: Registers a new social login provider
                description: Create Social Provider
                value:
                  name: Some Social Host
                  authType: SOCIAL
                  enabled: true
                  configUrl: https://some-social-host.com/.well-known/openid-configuration
                  redirectUrl: https://myapp.com/auth/handler
              Create SSO Provider:
                summary: Registers a new SSO provider
                description: Create SSO Provider
                value:
                  name: Some SSO Host
                  authType: SSO
                  enabled: true
                  configUrl: https://some-sso-host.com/.well-known/openid-configuration
                  redirectUrl: https://myapp.com/auth/handler
      responses:
        "200":
          description: Updated OIDC provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCProvider'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "409":
          description: OIDC provider already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "502":
          description: OIDC provider configuration does not match host URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/auth/oidc/providers/{providerName}:
    get:
      tags:
      - authentication
      summary: Get an OIDC provider
      description: "Gets an OIDC provider by name. If the well-known config for the\
        \ provider is determined to  have expired, the latest config is fetched and\
        \ retained, ensuring that the provider information returned is always current."
      operationId: getOIDCProvider
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: OIDC provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCProvider'
        "404":
          description: OIDC provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
    put:
      tags:
      - authentication
      summary: Update OIDC provider
      description: "Updates a named OIDC provider. During an update, the well-known\
        \ configuration is refreshed."
      operationId: updateOIDCProvider
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: "The new configuration values for an existing OIDC provider.\
          \ (The `name` may not be modified.) If the provider is enabled, the `redirectUrl`\
          \ back to your application must be specified. (Without the `redirectUrl`,\
          \ Nile cannot resolve authentication attempts.)"
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OIDCProvider'
            examples:
              Update Social Provider:
                summary: Updates the existing social provider configuration
                description: Update Social Provider
                value:
                  name: Some Social Host
                  authType: SOCIAL
                  enabled: true
                  configUrl: https://some-social-host.com/.well-known/openid-configuration
                  redirectUrl: https://myapp.com/auth/handler
              Update SSO Provider:
                summary: Updates the existing SSO provider configuration
                description: Update SSO Provider
                value:
                  name: Some SSO Host
                  authType: SSO
                  enabled: true
                  configUrl: https://some-sso-host.com/.well-known/openid-configuration
                  redirectUrl: https://myapp.com/auth/handler
      responses:
        "200":
          description: Updated OIDC provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCProvider'
        "400":
          description: OIDC provider name mismatch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: OIDC provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/auth/oidc/relyingparties:
    get:
      tags:
      - authentication
      summary: List relying parties
      description: Lists all OIDC relying parties in the database.
      operationId: listRelyingParties
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: List of relying parties
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OIDCRelyingParty'
      security:
      - jwtBearerAuth: []
    put:
      tags:
      - authentication
      summary: Update relying party
      description: "Updates an OIDC relying party. The `clientId`, `clientSecret`\
        \ and `enabled` properties may be modified."
      operationId: updateRelyingParty
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: "Configuration details for an existing OIDC relying party. The\
          \ `clientId`, `clientSecret` and `enabled` properties may be modified."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OIDCRelyingParty'
            examples:
              Create Relying Party Request:
                summary: Registers a relying party for an OIDC provider
                description: Create Relying Party Request
                value:
                  provider: GOOGLE
                  clientId: 0oa1b2c3d4e5f6g7h8i9j
                  clientSecret: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
                  enabled: true
      responses:
        "200":
          description: Relying party updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCRelyingParty'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Relying party not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - authentication
      summary: Create relying party
      description: Creates a relying party associated with a known OIDC provider.
      operationId: createRelyingParty
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: Configuration details for an OIDC relying party that relies on  a
          registered OIDC provider. This should include the client ID and secret for
          the relying party.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OIDCRelyingParty'
            examples:
              Create Relying Party Request:
                summary: Registers a relying party for an OIDC provider
                description: Create Relying Party Request
                value:
                  provider: GOOGLE
                  clientId: 0oa1b2c3d4e5f6g7h8i9j
                  clientSecret: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
                  enabled: true
      responses:
        "201":
          description: Relying party created successfully
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/auth/oidc/relyingparties/{relyingPartyId}:
    get:
      tags:
      - authentication
      summary: Get a relying party
      description: Get an OIDC relying party by its identifier.
      operationId: getRelyingParty
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: relyingPartyId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: The relying party
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OIDCRelyingParty'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Relying party not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/tenants/auth/oidc/locations:
    get:
      tags:
      - authentication
      summary: List SSO URLs
      description: Lists all SSO login URLs for all tenants in the database. The `provider`
        and `email` query parameters can be used to filter the results.
      operationId: listTenantSSOLocations
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: provider
        in: query
        schema:
          type: string
      - name: email
        in: query
        schema:
          type: string
      responses:
        "200":
          description: List of authorization URLs
          content:
            application/json:
              schema:
                type: string
                format: uri
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
  /databases/{databaseId}/tenants/auth/oidc/providers:
    get:
      tags:
      - authentication
      summary: List registered SSO providers
      description: Lists all SSO providers registered for all tenants. The `provider`
        and `email` query parameters can be used to filter the results.
      operationId: listTenantSSOProviders
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: provider
        in: query
        schema:
          type: string
      - name: email
        in: query
        schema:
          type: string
      responses:
        "200":
          description: List of registered providers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSSORegistration'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/tenants/{tenantId}/auth/oidc/providers/{providerName}:
    get:
      tags:
      - authentication
      summary: Get SSO registration
      description: Gets the configuration for a single sign-on provider registered
        for a tenant.
      operationId: getTenantSSORegistration
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: The registered configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSSORegistration'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    put:
      tags:
      - authentication
      summary: Update tenant SSO provider
      description: Updates a single sign-on provider configuration for a specific
        tenant.
      operationId: updateTenantSSOProvider
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: "Configuration details for a single sign-on provider. Any values\
          \ provided will overwrite existing values. If a value is not provided, the\
          \ existing value will be retained."
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantSSORegistration'
            examples:
              Partial Configuration:
                description: Partial Configuration
                value: |
                  {
                    "clientId": "0oa1b2c3d4e5f6g7h8i9j",
                    "clientSecret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
                  }
      responses:
        "200":
          description: Updated configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSSORegistration'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "502":
          description: Provider configuration does not match host URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - authentication
      summary: Register tenant SSO provider
      description: Registers a single sign-on provider configuration for a specific
        tenant.
      operationId: registerTenantSSOProvider
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: |-
          Configuration details for a single sign-on provider, including the email domains that should be associated with the provider.
          Note: the email domains you provide should usually correspond to the domains configured with the provider.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantSSORegistration'
            examples:
              Sample Okta Configuration:
                description: Sample Okta Configuration
                value:
                  configUrl: https://dev-123456.okta.com/.well-known/openid-configuration
                  clientId: 0oa1b2c3d4e5f6g7h8i9j
                  clientSecret: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2
                  emailDomains:
                  - mycompany.com
                  - anothercompany.com
                  enabled: true
      responses:
        "200":
          description: Registered configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantSSORegistration'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "409":
          description: Provider already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "502":
          description: Provider configuration does not match host URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/tenants/{tenantId}/auth/oidc/callback:
    get:
      tags:
      - users
      summary: Handle OIDC callback for a tenant user
      description: Handles the callback from an OIDC provider for a specific tenant.
        (This is the URL provided to the OIDC provider as the callback URL.)
      operationId: handleTenantOIDCCallback
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: code
        in: query
        required: true
        schema:
          type: string
      - name: state
        in: query
        required: true
        schema:
          type: string
      responses:
        "200":
          description: A form post to the configured redirect URL
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/OIDCFormPostView'
  /databases/{databaseId}/tenants/{tenantId}/auth/oidc/providers:
    get:
      tags:
      - authentication
      summary: List SSO registrations
      description: Lists all single sign-on provider configurations that are registered
        for a tenant.
      operationId: listTenantSSORegistrations
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: List of registered configurations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TenantSSORegistration'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/tenants/{tenantId}/auth/oidc/providers/{providerName}/login:
    get:
      tags:
      - authentication
      summary: Initiate OIDC login for a tenant
      description: Initiates the OIDC login flow for a registered authentication provider.
      operationId: loginTenantProvider
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      responses:
        "302":
          description: Redirect to the provider's login page
        "404":
          description: Unknown OIDC provider
  /databases/{databaseId}/tenants:
    get:
      summary: List tenants
      description: "Lists all tenants in a database. If a developer token is provided,\
        \ all tenants are listed. If a user token is provided, only tenants that the\
        \ user is a member of are listed."
      operationId: listTenants
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: List of tenants
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tenant'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - tenants
      summary: Create a tenant
      description: Creates a new tenant in a database.
      operationId: createTenant
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: A wrapper for the tenant name.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTenantRequest'
            examples:
              Create Tenant Request:
                summary: Creates a named tenant
                description: Create Tenant Request
                value:
                  name: My Sandbox
      responses:
        "201":
          description: Tenant created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Database not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/tenants/{tenantId}:
    get:
      tags:
      - tenants
      summary: Get a tenant
      description: Gets a tenant from a database.
      operationId: getTenant
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: A Tenant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tenant'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Tenant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    put:
      tags:
      - tenants
      summary: Update a tenant
      description: Updates a tenant. Only the tenant name may be updated.
      operationId: updateTenant
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: A wrapper for the tenant name.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTenantRequest'
            examples:
              Update Tenant Request:
                summary: Updates a tenant name
                description: Update Tenant Request
                value:
                  name: Customer One
      responses:
        "200":
          description: Tenant updated
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tenant'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Tenant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    delete:
      tags:
      - tenants
      summary: Deletes a tenant.
      operationId: deleteTenant
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        "204":
          description: Tenant deleted
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: Tenant not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/tenants/{tenantId}/users:
    get:
      tags:
      - users
      summary: List tenant users
      description: Lists users that are associated with the specified tenant.
      operationId: listTenantUsers
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Users found
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - users
      summary: Create a user in a tenant
      description: Creates a new user and associates that user with the specified
        tenant.
      operationId: createTenantUser
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: |
          The email and password combination the user will use to authenticate.
          The `name` is optional; if provided it will be recorded in the `users` table.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBasicUserRequest'
            examples:
              Create User Request:
                summary: Creates a user with basic credentials
                description: Create User Request
                value:
                  email: a.user@somedomain.com
                  password: somepassword
                  name: A. User
      responses:
        "201":
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginUserResponse'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/tenants/{tenantId}/users/{userId}:
    get:
      tags:
      - users
      summary: Get a user in a tenant
      description: "Gets information about a user, but only if that user belongs to\
        \ the tenant specified. If the user does not belong to the tenant, this returns\
        \ 404 (Not Found)."
      operationId: getTenantUser
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/tenants/{tenantId}/users/login:
    post:
      tags:
      - users
      summary: Login a user in a tenant
      description: "Authenticates a user, ensuring that the user is a member of the\
        \ tenant. If the user is not a member of the tenant, this returns 401 (Unauthorized)."
      operationId: loginTenantUser
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: tenantId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: The email and password combination the user registered with.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              Login Request:
                description: Login Request
                value:
                  email: a.user@somedomain.com
                  password: somepassword
      responses:
        "200":
          description: User logged in successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginUserResponse'
        "401":
          description: User authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
  /databases/{databaseId}/users:
    get:
      tags:
      - users
      summary: List database users
      description: Lists all users in the database
      operationId: listUsers
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: Users found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    post:
      tags:
      - users
      summary: Create a new user
      description: Creates a new user using basic credentials—email address and password.
      operationId: createUser
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: |-
          The email and password combination the user will use to authenticate.
          The `name` is optional; if provided it will be recorded in the `users` table.
          The `newTenant` is optional; if provided, it is used as the name of a new tenant record associated with the newly created user.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBasicUserRequest'
            examples:
              Create User Request:
                summary: Creates a user with basic credentials
                description: Create User Request
                value:
                  email: a.user@somedomain.com
                  password: somepassword
                  name: A. User
              Create User Request with Tenant:
                summary: Creates a user and a new tenant for that user
                description: Create User Request with Tenant
                value:
                  email: a.user@somedomain.com
                  password: somepassword
                  name: A. User
                  newTenant: My Sandbox
      responses:
        "201":
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginUserResponse'
  /databases/{databaseId}/users/{userId}:
    get:
      tags:
      - users
      summary: Get a user
      description: Gets a user by id.
      operationId: getUser
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    put:
      tags:
      - users
      summary: Update a user
      description: Updates user attributes by id.
      operationId: updateUser
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: userId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          '*/*':
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
        required: true
      responses:
        "200":
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
    delete:
      tags:
      - users
      summary: Delete a user
      description: Deletes a user from the database
      operationId: deleteUser
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: userId
        in: path
        required: true
        schema:
          type: string
      responses:
        "204":
          description: User deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/users/oidc/callback:
    get:
      tags:
      - users
      summary: Handle OIDC callback for a user
      description: Handles the callback from an OIDC provider. (This is the URL provided
        to the OIDC provider as the callback URL.)
      operationId: handleOIDCCallbackDP
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: code
        in: query
        required: true
        schema:
          type: string
      - name: state
        in: query
        required: true
        schema:
          type: string
      responses:
        "200":
          description: A form post to the configured redirect URL
          content:
            text/html:
              schema:
                $ref: '#/components/schemas/OIDCFormPostView'
  /databases/{databaseId}/users/me:
    get:
      tags:
      - users
      summary: Identify the user
      description: Returns information about the user associated with the token provided
      operationId: identifyUser
      responses:
        "200":
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        "404":
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      security:
      - jwtBearerAuth: []
  /databases/{databaseId}/users/login:
    post:
      tags:
      - users
      summary: Login a user
      description: Login a user with email and password
      operationId: loginUser
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: The email and password combination the user registered with.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
            examples:
              Login Request:
                description: Login Request
                value:
                  email: a.user@somedomain.com
                  password: somepassword
      responses:
        "200":
          description: User logged in successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginUserResponse'
        "401":
          description: User authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
  /databases/{databaseId}/users/oidc/{providerName}/login:
    get:
      tags:
      - users
      summary: Initiate OIDC user login
      description: Initiates the OIDC login flow for a known authentication provider.
      operationId: loginOIDCUserDP
      parameters:
      - name: databaseId
        in: path
        required: true
        schema:
          type: string
      - name: providerName
        in: path
        required: true
        schema:
          type: string
      - name: newTenant
        in: query
        schema:
          type: string
      - name: nonce
        in: query
        schema:
          type: string
      responses:
        "302":
          description: Redirect to the provider's login page
        "404":
          description: Unknown OIDC provider
components:
  schemas:
    CreateCredentialResponse:
      required:
      - database
      - id
      - password
      type: object
      properties:
        id:
          type: string
        database:
          $ref: '#/components/schemas/Database'
        password:
          type: string
    Database:
      required:
      - id
      - name
      - region
      - status
      - workspace
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        workspace:
          $ref: '#/components/schemas/Workspace'
        status:
          type: string
          enum:
          - PENDING
          - REQUESTED
          - BUILT
          - READY
        region:
          type: string
          enum:
          - AWS_US_WEST_2
          - AWS_EU_CENTRAL_1
    Workspace:
      required:
      - name
      - slug
      type: object
      properties:
        name:
          type: string
        slug:
          type: string
          readOnly: true
    APIError:
      required:
      - errorCode
      - message
      - statusCode
      type: object
      properties:
        errorCode:
          type: string
          enum:
          - internal_error
          - bad_request
          - unsupported_operation
          - entity_not_found
          - duplicate_entity
          - invalid_credentials
          - unknown_oidc_provider
          - unknown_oidc_party
          - provider_already_exists
          - provider_config_error
          - provider_mismatch
          - provider_update_error
          - provider_disabled
          - session_state_missing
          - session_state_mismatch
          - oidc_code_missing
          - tenant_not_found
          - constraint_violation
          - sql_exception
          - db_creation_failure
          - db_status_failure
          - db_initialization_failure
          - db_config_missing
          - unauthorized_workspace_access
          - email_send_failure
          - jdbc_exception
          - oidc_exception
          - region_mismatch
          - credential_creation_failure
          - credential_propagation_failure
        message:
          type: string
        statusCode:
          type: integer
          format: int32
    Credential:
      required:
      - database
      - id
      type: object
      properties:
        id:
          type: string
        database:
          $ref: '#/components/schemas/Database'
    GetDatabaseResponse:
      required:
      - apiHost
      - id
      - name
      - region
      - status
      - workspace
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        workspace:
          $ref: '#/components/schemas/Workspace'
        status:
          type: string
          enum:
          - PENDING
          - REQUESTED
          - BUILT
          - READY
        region:
          type: string
          enum:
          - AWS_US_WEST_2
          - AWS_EU_CENTRAL_1
        apiHost:
          type: string
          format: uri
        dbHost:
          type: string
          format: uri
    DatabaseUser:
      type: object
      properties:
        id:
          type: string
    CreateDatabaseRequest:
      required:
      - databaseName
      type: object
      properties:
        databaseName:
          type: string
        region:
          type: string
    Developer:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
        workspaces:
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/Workspace'
        databases:
          uniqueItems: true
          type: array
          items:
            type: string
    DeveloperInvite:
      required:
      - email
      - id
      - sender
      - verificationState
      - workspace
      type: object
      properties:
        id:
          type: string
        sender:
          $ref: '#/components/schemas/Developer'
        email:
          type: string
        workspace:
          $ref: '#/components/schemas/Workspace'
        verificationState:
          type: string
          enum:
          - EMAIL_PENDING
          - EMAIL_SENT
          - VERIFIED
          - EXPIRED
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    CreateInviteRequest:
      required:
      - email
      type: object
      properties:
        email:
          type: string
    EmailVerificationStateFilter:
      type: object
    OIDCFormPostView:
      type: object
      properties:
        tenantId:
          type: string
    CreateWorkspaceRequest:
      required:
      - name
      type: object
      properties:
        name:
          type: string
    JsonNode:
      type: object
    OIDCProvider:
      required:
      - authType
      - name
      type: object
      properties:
        name:
          type: string
        authType:
          type: string
          enum:
          - SSO
          - SOCIAL
        redirectUrl:
          type: string
          format: uri
        enabled:
          type: boolean
        configUrl:
          type: string
          format: uri
        config:
          $ref: '#/components/schemas/JsonNode'
        ttl_sec:
          type: integer
          format: int32
    OIDCRelyingParty:
      required:
      - clientId
      - clientSecret
      - provider
      type: object
      properties:
        id:
          type: string
        tenantId:
          type: string
        provider:
          type: string
        clientId:
          type: string
        clientSecret:
          type: string
        emailDomains:
          type: array
          items:
            type: string
        enabled:
          type: boolean
    TenantSSORegistration:
      required:
      - clientId
      - configUrl
      - provider
      - tenantId
      type: object
      properties:
        id:
          type: string
          readOnly: true
        tenantId:
          type: string
        provider:
          type: string
        configUrl:
          type: string
          format: uri
        clientId:
          type: string
        emailDomains:
          type: array
          items:
            type: string
        enabled:
          type: boolean
    Tenant:
      required:
      - id
      type: object
      properties:
        id:
          type: string
        name:
          type: string
    CreateTenantRequest:
      required:
      - name
      type: object
      properties:
        name:
          type: string
    LoginUserResponse:
      required:
      - id
      - token
      type: object
      properties:
        id:
          type: string
        tenants:
          uniqueItems: true
          type: array
          items:
            type: string
        token:
          $ref: '#/components/schemas/Token'
    Token:
      required:
      - jwt
      - type
      type: object
      properties:
        jwt:
          type: string
        maxAge:
          minimum: 0
          type: integer
          format: int32
        type:
          type: string
          enum:
          - ACCESS_TOKEN
          - REFRESH_TOKEN
          - ID_TOKEN
    CreateBasicUserRequest:
      required:
      - email
      - password
      type: object
      properties:
        email:
          type: string
        password:
          type: string
        name:
          type: string
        givenName:
          type: string
        familyName:
          type: string
        picture:
          type: string
        newTenant:
          type: string
    User:
      type: object
      properties:
        id:
          type: string
        tenants:
          uniqueItems: true
          type: array
          items:
            type: string
        email:
          type: string
        name:
          type: string
        givenName:
          type: string
        familyName:
          type: string
        picture:
          type: string
        created:
          type: string
          format: date-time
        updated:
          type: string
          format: date-time
    LoginRequest:
      required:
      - email
      - password
      type: object
      properties:
        email:
          type: string
        password:
          type: string
    UpdateUserRequest:
      type: object
      properties:
        email:
          type: string
        name:
          type: string
        givenName:
          type: string
        familyName:
          type: string
        picture:
          type: string
    LogicalDatabase:
      required:
      - id
      - pdb
      - placementStrategy
      - region
      - status
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - REQUESTED
          - BUILT
          - READY
        pdb:
          type: integer
          format: int32
        placementStrategy:
          type: string
          enum:
          - RANDOM
          - SINGLE
        region:
          type: string
          enum:
          - AWS_US_WEST_2
          - AWS_EU_CENTRAL_1
    GetDatabaseStatusResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - PENDING
          - REQUESTED
          - BUILT
          - READY
    PrincipalResponse:
      type: object
      properties:
        id:
          type: string
        principalType:
          type: string
          enum:
          - DEVELOPER
          - USER
          - INTERNAL
        email:
          type: string
        name:
          type: string
  securitySchemes:
    jwtBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
