Dash0 Manage Auth Tokens API

openapi: 3.2.0
info:
  title: Dash0 Manage Auth Tokens API
  version: 1.0.0
  description: '## Selecting a dataset


    Endpoints that operate on a single dataset take it from the `dataset` query parameter, or from the `Dash0-Dataset` request header when the query parameter is absent. When both are present the query parameter wins.


    If neither is given, the request falls back to the organization''s `default` dataset — a token that is restricted to specific datasets is rejected with `403 Forbidden` in that case, so always select a dataset explicitly when using a dataset-restricted token.


    ## Resource origins


    Most resources take an optional `metadata.labels["dash0.com/origin"]`. It is a stable identifier you choose for a resource you manage as code, so your Terraform configuration, Kubernetes manifests, CLI scripts or your own tooling can address the same resource on every apply without having to store the id Dash0 generated.


    An origin is unique per organization, not per dataset. Two resources of the same type in one organization cannot share an origin, even when they live in different datasets. If you want what is really the same rule in several datasets, put the dataset in the origin, for example `probabilistic-request-sampling-sandbox` and `probabilistic-request-sampling-nonprod`. The Dash0 Kubernetes operator does the same with the origins it generates. A duplicate origin is rejected with `400`.


    You cannot change an origin. Dash0 records it when the resource is created and ignores it on later updates, so you can read a resource, edit it and send it back without stripping the label out first.


    Endpoints with an `{originOrId}` path parameter take either identifier. A value that is not a UUID is read as an origin. A `PUT` to an origin that does not exist yet creates the resource with that origin, so you can apply the same manifest repeatedly.


    ## Request body size limit


    Most API endpoints enforce a maximum request body size of 256KB. Bulk

    endpoints accept a larger body size per request to accommodate batched

    payloads.


    Requests exceeding the applicable limit are rejected with a

    `413 Content Too Large` response.'
servers:
- url: https://api.eu-west-1.aws.dash0.com
  description: API endpoint for AWS region EU (Ireland)
- url: https://api.eu-central-1.aws.dash0.com
  description: API endpoint for AWS region EU (Germany)
- url: https://api.us-east-1.aws.dash0.com
  description: API endpoint for AWS region US (N. Virginia)
- url: https://api.us-west-2.aws.dash0.com
  description: API endpoint for AWS region US (Oregon)
- url: https://api.europe-west4.gcp.dash0.com
  description: API endpoint for GCP region EU (Netherlands)
tags:
- name: Manage Auth Tokens
paths:
  /api/auth-tokens:
    get:
      summary: List all auth tokens for the organization
      description: 'Returns all auth tokens in your organization. The secret is not returned: `spec.token` is

        only in the response that creates a token.'
      responses:
        '200':
          description: The organization's auth tokens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenListResponse'
        '403':
          description: 'The caller is not an organization admin user, or is an auth token that lacks the `*` action

            or has a dataset or signal restriction. Only fully unrestricted callers may manage auth tokens.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Auth Tokens
      operationId: getApiAuthTokens
      x-operation-id-source: derived
    post:
      summary: Create an auth token
      description: 'Creates an auth token. The secret is generated by the server and returned in `spec.token`

        in this response only; store it, because no later read returns it. The request must not

        carry `spec.token`: a request that sends one returns `400`.

        `metadata.labels["dash0.com/id"]` must not be set. `metadata.labels["dash0.com/origin"]` must be

        unique in your organization and must not be a UUID; a machine token that has no user gets an

        `api-` origin when none is given. The origin cannot be changed afterwards. `apiVersion` is

        required; a missing or unsupported value returns `400`.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthTokenCreateRequest'
      responses:
        '200':
          description: The auth token was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        '403':
          description: 'The caller is not an organization admin user, or is an auth token that lacks the `*` action

            or has a dataset or signal restriction. Only fully unrestricted callers may manage auth tokens.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Auth Tokens
      operationId: postApiAuthTokens
      x-operation-id-source: derived
  /api/auth-tokens/{originOrId}:
    delete:
      summary: Delete a specific auth token
      description: 'Deletes the auth token. Deleting the last remaining auth token of your organization is refused

        with `400`.'
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: Auth token origin or ID.
      responses:
        '200':
          description: The auth token was deleted.
        '403':
          description: 'The caller is not an organization admin user, or is an auth token that lacks the `*` action

            or has a dataset or signal restriction. Only fully unrestricted callers may manage auth tokens.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Auth Tokens
      operationId: deleteApiAuthTokensByOriginOrId
      x-operation-id-source: derived
    get:
      summary: Retrieve a specific auth token
      description: 'Returns the auth token with the given origin or ID. The secret is not returned: `spec.token`

        is only in the response that creates a token.'
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: Auth token origin or ID.
      responses:
        '200':
          description: The requested auth token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        '403':
          description: 'The caller is not an organization admin user, or is an auth token that lacks the `*` action

            or has a dataset or signal restriction. Only fully unrestricted callers may manage auth tokens.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Auth Tokens
      operationId: getApiAuthTokensByOriginOrId
      x-operation-id-source: derived
    put:
      summary: Update a specific auth token
      description: 'Updates an auth token, or creates it when no token has the given origin (upsert by origin).

        The request must not carry `spec.token`: the secret is generated by Dash0 and a request that

        sends one returns `400`. Changing the origin is rejected with `400`. The response includes

        `spec.token` only when this request created the token.

        Omitting any spec field leaves its stored value unchanged. `apiVersion` is required; a missing

        or unsupported value returns `400`.'
      parameters:
      - in: path
        name: originOrId
        schema:
          type: string
        required: true
        description: Auth token origin or ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthTokenUpdateRequest'
      responses:
        '200':
          description: The auth token was updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
        '403':
          description: 'The caller is not an organization admin user, or is an auth token that lacks the `*` action

            or has a dataset or signal restriction. Only fully unrestricted callers may manage auth tokens.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: In case any error happens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Manage Auth Tokens
      operationId: putApiAuthTokensByOriginOrId
      x-operation-id-source: derived
components:
  schemas:
    Error:
      properties:
        code:
          type: integer
          description: 'HTTP status code.

            '
        type:
          type: string
          description: 'Stable `snake_case` identifier for the kind of error, safe for clients to branch on. Not

            an enum: treat an unrecognized value the same as an absent one and fall back to `message`,

            so a new error kind never breaks the contract. Optional — absent means unclassified, not

            success.

            '
        message:
          type: string
          description: 'Human-readable description of the error. Safe to display.

            '
        traceId:
          type: string
          description: 'Trace ID for the request that produced the error, for correlating with logs and traces.

            '
      required:
      - code
      - message
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
      - error
    AuthTokenResponseDefinition:
      properties:
        apiVersion:
          type: string
          example: dash0.com/v1alpha1
        kind:
          type: string
          enum:
          - Dash0AuthToken
        metadata:
          $ref: '#/components/schemas/AuthTokenMetadata'
        spec:
          $ref: '#/components/schemas/AuthTokenResponseSpec'
      required:
      - apiVersion
      - kind
      - metadata
      - spec
    SignalRestriction:
      type: string
      description: 'Whether the list of signal types on an auth token limits what it can reach. Clients must accept

        values they do not recognize.

        '
      enum:
      - restricted
      - unrestricted
    AuthTokenResponseSpec:
      allOf:
      - $ref: '#/components/schemas/AuthTokenSpec'
      - type: object
        properties:
          token:
            type: string
            description: 'The secret customers use as a Bearer token to send telemetry to Dash0. Generated by

              Dash0 and returned only in the response that creates the token (POST, or a PUT that

              creates). Never part of a request: a request that carries `spec.token` returns 400.

              '
    AuthTokenCreateRequest:
      $ref: '#/components/schemas/AuthTokenDefinition'
    AuthTokenSpec:
      description: 'Every field is optional. Omitted on create takes the server default. Omitted on update keeps

        the stored value.

        '
      properties:
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
        scope:
          $ref: '#/components/schemas/AuthTokenScope'
        ingestion:
          $ref: '#/components/schemas/AuthTokenIngestion'
    SignalType:
      type: string
      description: Enumeration of valid signal types in Dash0.
      enum:
      - logs
      - metricDataPoints
      - spans
      - profiles
      - webEvents
      - syntheticApiChecks
      - agent0Credits
      - codeAgentCommitters
      - signalControlEdgeLogs
      - signalControlEdgeMetrics
      - signalControlEdgeTraces
      - signalControlManagedLogs
      - signalControlManagedMetrics
      - signalControlManagedTraces
      - signalControlManagedWebEvents
      - sessionReplays
    Dataset:
      type: string
      pattern: ^[a-zA-Z0-9_-]{3,26}$
      description: Optional dataset to query across. Defaults to whatever is configured to be the default dataset for the organization.
    AuthTokenSignalScope:
      properties:
        restriction:
          description: 'Whether `types` limits the signal types that can be ingested via this token. Defaults to

            `unrestricted`, i.e., all signal types are accepted. Clients must accept values they do

            not recognize.

            '
          $ref: '#/components/schemas/SignalRestriction'
        types:
          description: 'The signal types the token is limited to. Read only when `restriction` is `restricted`.

            '
          type: array
          items:
            $ref: '#/components/schemas/SignalType'
    AuthTokenIngestion:
      properties:
        defaultDataset:
          description: 'The dataset used when telemetry arrives via this token without naming one. Defaults to

            the organization''s default dataset.

            '
          $ref: '#/components/schemas/Dataset'
    AuthTokenScope:
      description: 'What data the token can reach. Both groups default to `unrestricted`.

        '
      properties:
        datasets:
          $ref: '#/components/schemas/AuthTokenDatasetScope'
        signals:
          $ref: '#/components/schemas/AuthTokenSignalScope'
    CrdSource:
      description: "Origin of a Dash0 resource, derived from `dash0.com/origin` on read.\n- `ui`: created interactively in the Dash0 UI.\n- `terraform`: managed via the Dash0 Terraform provider.\n- `operator`: managed via the Dash0 Kubernetes operator.\n- `dash0-cli`: managed via the Dash0 CLI.\n- `platform`: owned by Dash0 rather than by anyone in your organization. Covers both\n  resources Dash0 generates from another resource you own (the recording rules an SLO\n  produces) and resources Dash0 ships with the product (the built-in views).\n- `identity-provider`: a team whose membership Dash0 keeps in sync with a directory\n  group from the organization's identity provider. Membership edits made by hand\n  revert on the next reconcile.\n- `api`: created directly through the API, and the fallback for any origin whose\n  prefix is not recognized.\n\nNew values may be added over time. Treat an unrecognized value as `api`\nrather than rejecting the response.\n"
      type: string
      enum:
      - ui
      - terraform
      - operator
      - dash0-cli
      - platform
      - identity-provider
      - api
    AuthTokenLabels:
      properties:
        dash0.com/id:
          type: string
          format: uuid
          description: 'The auth token UUID. Server-set; not accepted on create.

            '
        dash0.com/origin:
          type: string
          description: 'External identifier for this auth token. Must be unique per organization and must not be a

            UUID. Used by Infrastructure-as-Code tools (Terraform, Kubernetes operator).

            Auto-generated as `api-<uuid>` for machine tokens that have no user. Immutable once set.

            A PUT to an origin that does not exist yet creates the token.

            '
        dash0.com/source:
          $ref: '#/components/schemas/CrdSource'
    AuthTokenResponse:
      $ref: '#/components/schemas/AuthTokenResponseDefinition'
    AuthTokenDatasetScope:
      properties:
        restriction:
          description: 'Whether `slugs` limits the datasets that data can be reported into via this token.

            Defaults to `unrestricted`, i.e., data can be reported to any dataset. Clients must

            accept values they do not recognize.

            '
          $ref: '#/components/schemas/DatasetRestriction'
        slugs:
          description: 'The dataset slugs the token is limited to. Read only when `restriction` is `restricted`.

            '
          type: array
          items:
            $ref: '#/components/schemas/Dataset'
    AuthTokenMetadata:
      properties:
        name:
          type: string
          description: 'Human-readable name for the auth token.

            '
        labels:
          $ref: '#/components/schemas/AuthTokenLabels'
        annotations:
          $ref: '#/components/schemas/AuthTokenAnnotations'
      required:
      - name
    AuthTokenDefinition:
      properties:
        apiVersion:
          type: string
          description: 'Version of the auth token document format. Required on create and update; the only

            supported value is `dash0.com/v1alpha1`, and any other value returns 400. Returned on

            every read.

            '
          example: dash0.com/v1alpha1
        kind:
          type: string
          enum:
          - Dash0AuthToken
        metadata:
          $ref: '#/components/schemas/AuthTokenMetadata'
        spec:
          $ref: '#/components/schemas/AuthTokenSpec'
      required:
      - apiVersion
      - kind
      - metadata
      - spec
    AuthTokenUpdateRequest:
      $ref: '#/components/schemas/AuthTokenDefinition'
    AuthTokenListResponse:
      type: array
      items:
        $ref: '#/components/schemas/AuthTokenResponse'
    DatasetRestriction:
      type: string
      description: 'Whether the list of datasets on an auth token limits what it can reach. Clients must accept

        values they do not recognize.

        '
      enum:
      - restricted
      - unrestricted
    AuthTokenAnnotations:
      properties:
        dash0.com/created-at:
          type: string
          format: date-time
    Action:
      type: string
      description: 'Not defined as an enum, because we will eventually support wildcards like `ingest:*`.

        '
x-provenance:
  method: harvested
  publisher: Dash0
  source: https://api.eu-central-1.aws.dash0.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)