> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simforge.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# The agent sign-in recipe (auth.md)

> The auth.md recipe (https://workos.com/auth-md) for this host, also at `/.well-known/auth.md`: how an AI agent registers, is approved by a person and calls `/api/v1`. Generated from the same source as the metadata.



## OpenAPI

````yaml /api-reference/openapi.json get /auth.md
openapi: 3.1.0
info:
  title: SimForge Cloud API
  version: '2026-10-24'
  description: >-
    The public SimForge API: what `simforge --cloud`, `simforge login` and the
    Python client call. Authenticate with a bearer token: the access token
    `simforge login` stores, an AI agent's access token (its recipe is
    `/auth.md`), or an `sfk_` API key. A `/api/v1` 401 carries
    `WWW-Authenticate: Bearer
    resource_metadata="<host>/.well-known/oauth-protected-resource"`. `/api/v1`
    errors are an `ErrorEnvelope`; `/api/cli` and `/agent` errors are an OAuth
    error object.


    Versions: send `SimForge-Version: <date>` (2026-10-01, 2026-10-21,
    2026-10-22, 2026-10-23, 2026-10-24) and every `/api/v1` response is in that
    version's shape and names it in the same header; this document describes
    2026-10-24. A request without the header gets 2026-10-01, where an error's
    hint is `detail.hint` and `GET /api/v1/evaluations` names its rows `jobs`. A
    header that is not a date, or a date before 2026-10-01, is `400
    bad_request`. Every response also carries `SimForge-Cli-Minimum`: the oldest
    `simforge` CLI the server serves.


    Retries: from 2026-10-21, send a new `Idempotency-Key` (1-255 characters)
    with every POST, PUT, PATCH and DELETE, and the same key when retrying that
    request. The first request's answer is kept for 24 hours and a repeat gets
    it again with `Idempotent-Replayed: true`; the key with any other request,
    or while the first is still running, is `409 idempotency_conflict`
    (`retryable` while running). A 5xx answer is not kept. Creating an API key
    refuses a key (its secret is shown once).
  license:
    name: Apache-2.0
    identifier: Apache-2.0
servers:
  - url: https://dev.simforge.ai
    description: Development (dev.simforge.ai)
security: []
tags:
  - name: Sign-in
    description: >-
      `simforge login`: OAuth 2.0 device and browser sign-in for the CLI, the
      session behind a token. AI agents sign in through auth.md (`/auth.md`):
      register, a person approves, then the claim and JWT-bearer grants.
  - name: Account
    description: The principal, its workspaces, API keys and usage, and system status.
  - name: Runs
    description: >-
      Cloud runs (`--cloud`): renders, simulations, Recast log ingestion and
      transfers, their events and artifacts.
  - name: Models
    description: Customer fine-tunes and their workspace-owned model weights.
  - name: Datasets
    description: >-
      Datasets, their files as signed links (`simforge.dataset-files/v1`,
      `simforge datasets pull`), and copies out of shared datasets (SIMLOG-25k).
  - name: Maps and vehicles
    description: >-
      Maps the workspace can use, the vehicles a scenario can bind and the asset
      gallery.
  - name: Authoring
    description: >-
      Hosted scenario authoring: drafts, transactions, validation and map
      discovery.
  - name: Distribution
    description: >-
      The runtime and map pack agreement and signed downloads (`simforge runtime
      install`, `simforge maps pull`).
  - name: Telemetry
    description: Runtime usage telemetry, a condition of the runtime terms.
  - name: Benchmark
    description: Renderer benchmark results and scene packs (`simforge bench`).
  - name: Challenge
    description: >-
      The driving challenge: team, registry login and submissions (`simforge
      challenge`).
paths:
  /auth.md:
    get:
      tags:
        - Sign-in
      summary: The agent sign-in recipe (auth.md)
      description: >-
        The auth.md recipe (https://workos.com/auth-md) for this host, also at
        `/.well-known/auth.md`: how an AI agent registers, is approved by a
        person and calls `/api/v1`. Generated from the same source as the
        metadata.
      operationId: getAuthMd
      responses:
        '200':
          description: The recipe.
          content:
            text/markdown:
              schema:
                type: string
      security: []

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.