Element Biosciences Auth Service API

openapi: 3.2.0
info:
  title: Element Biosciences Cloud Auth Service API
  description: 'The Element Biosciences Cloud API provides programmatic access to data in

    the Element Biosciences Cloud platform: instrument runs (sequencing and

    multiomics), workflow executions, registered instruments, storage

    connections, and the files those resources produce.'
  version: 1.0.0
  contact:
    name: Element Biosciences
    url: https://www.elembio.io
servers:
- url: https://cloud-api.usw2.elembio.io
security:
- apiKey: []
tags:
- name: Auth Service
  description: AuthService reports information about the API key making the request.
paths:
  /v1/auth:
    get:
      tags:
      - Auth Service
      summary: GetAuth
      description: 'Return the tenant the current API key belongs to. This endpoint requires a

        valid API key but no additional scope, so it is a convenient way to verify

        that a key is working.'
      operationId: AuthService_GetAuth
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/elembio.cloud.v1.GetAuthResponse'
        '400':
          description: Bad request — the request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — the API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — the API key lacks the required scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found — the requested resource does not exist or is not accessible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ErrorDetail:
      type: object
      description: Structured error detail with a machine-readable reason code.
      properties:
        '@type':
          type: string
          description: Type identifier for this error detail
        reason:
          type: string
          description: 'Machine-readable error code identifying the specific failure

            (e.g. RUN_NOT_FOUND, INVALID_API_KEY, INSUFFICIENT_SCOPE).

            '
          examples:
          - RUN_NOT_FOUND
          - INVALID_API_KEY
          - MISSING_API_KEY
          - INSUFFICIENT_SCOPE
          - INTERNAL_ERROR
        domain:
          type: string
          description: Identifies the system that generated the error
          const: cloud-api.elembio.io
        metadata:
          type: object
          description: Additional context for the error
          properties:
            request_id:
              type: string
              description: Request ID matching the X-Request-ID response header
      required:
      - reason
      - domain
    Error:
      type: object
      description: Error response returned by all endpoints when a request fails.
      properties:
        code:
          type: integer
          description: Numeric status code corresponding to the HTTP response status
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          description: Structured error details with machine-readable reason codes
          items:
            $ref: '#/components/schemas/ErrorDetail'
      required:
      - code
      - message
      examples:
      - code: 404
        message: Run not found.
        details:
        - reason: RUN_NOT_FOUND
          domain: cloud-api.elembio.io
          metadata:
            request_id: 550e8400-e29b-41d4-a716-446655440000
      - code: 401
        message: Invalid API key.
        details:
        - reason: INVALID_API_KEY
          domain: cloud-api.elembio.io
          metadata:
            request_id: 550e8400-e29b-41d4-a716-446655440001
    elembio.cloud.v1.GetAuthResponse:
      type: object
      properties:
        tenantId:
          type: string
          title: tenant_id
          description: Identifier of the tenant the API key belongs to.
        scopes:
          type: array
          items:
            type: string
          title: scopes
          description: "Scopes granted to the API key making the request, e.g. \"runs:read\" or\n \"storage:download:stc_abc123/data/\". A resource-scoped key reports its\n resource-qualified scopes; an unrestricted key reports its family-level\n scopes. An empty list means the key has no resource scopes (only the\n auth-level access needed to reach this endpoint)."
      title: GetAuthResponse
      additionalProperties: false
      description: Response describing the authenticated API key.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key obtained from the Element Biosciences Cloud console