openapi: 3.0.1
info:
  title: Preset Authentication Workspaces API
  description: 'Specification of the Preset API. Preset is a managed cloud BI and analytics platform powered by Apache Superset. The API has two surfaces: the Preset Manager API at https://api.app.preset.io (authentication, teams, workspaces, guest tokens) and a per-workspace proxy to the underlying Apache Superset REST API reached at the workspace hostname pattern {workspace-slug}.{region}.app.preset.io. Authenticate by exchanging an API token name and secret at POST /v1/auth/ for a JWT, then pass it as a Bearer token on subsequent requests.'
  termsOfService: https://preset.io/terms-and-conditions/
  contact:
    name: Preset Support
    url: https://docs.preset.io
  version: '1.0'
servers:
- url: https://api.app.preset.io
  description: Preset Manager API (authentication, teams, workspaces, guest tokens)
- url: https://{workspaceSlug}.{region}.app.preset.io
  description: Per-workspace proxy to the Apache Superset REST API
  variables:
    workspaceSlug:
      default: my-workspace
      description: The workspace slug returned by the workspaces endpoint
    region:
      default: us2a
      description: The workspace region (e.g. us2a)
tags:
- name: Workspaces
paths:
  /v1/teams/{teamName}/workspaces/:
    get:
      operationId: getWorkspaces
      tags:
      - Workspaces
      summary: List workspaces in a team
      description: Returns the workspaces belonging to a team, including each workspace name (slug) and region used to construct the workspace proxy hostname.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/TeamName'
      responses:
        '200':
          description: A list of workspaces.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceList'
    post:
      operationId: createWorkspace
      tags:
      - Workspaces
      summary: Create a workspace in a team
      description: Creates a new Superset-backed workspace within a team.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/TeamName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceCreate'
      responses:
        '201':
          description: The created workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
  /v1/teams/{teamName}/workspaces/{workspaceName}/guest-token/:
    post:
      operationId: createGuestToken
      tags:
      - Workspaces
      summary: Create a guest token for an embedded dashboard
      description: Mints a short-lived guest token (expires after about five minutes) that authenticates an end user to view an embedded dashboard for the given workspace.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/TeamName'
      - $ref: '#/components/parameters/WorkspaceName'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GuestTokenRequest'
      responses:
        '200':
          description: A guest token payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GuestTokenResponse'
components:
  schemas:
    GuestTokenRequest:
      type: object
      properties:
        user:
          type: object
          description: Identity attributes for the guest user.
        resources:
          type: array
          items:
            type: object
          description: The embedded resources (e.g. dashboard id) being granted.
        rls:
          type: array
          items:
            type: object
          description: Row level security rules applied to the guest session.
    GuestTokenResponse:
      type: object
      properties:
        payload:
          type: object
          properties:
            token:
              type: string
              description: The short-lived guest token.
    WorkspaceCreate:
      type: object
      required:
      - title
      properties:
        title:
          type: string
        region:
          type: string
    WorkspaceList:
      type: object
      properties:
        payload:
          type: array
          items:
            $ref: '#/components/schemas/Workspace'
    Workspace:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          description: The workspace slug used in the proxy hostname.
        title:
          type: string
        region:
          type: string
          description: The workspace region used in the proxy hostname.
        hostname:
          type: string
          description: Fully qualified workspace hostname, e.g. my-workspace.us2a.app.preset.io.
  parameters:
    TeamName:
      name: teamName
      in: path
      required: true
      description: The team name (slug).
      schema:
        type: string
    WorkspaceName:
      name: workspaceName
      in: path
      required: true
      description: The workspace name (slug).
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT obtained from POST /v1/auth/ by exchanging an API token name and secret. Passed as Authorization: Bearer <token>.'