> ## 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.

# Protected resource metadata

> RFC 9728 protected resource metadata of `/api/v1`, also served at `/.well-known/oauth-protected-resource` (the URL every `/api/v1` 401 names in `WWW-Authenticate: Bearer resource_metadata=…`) and `/.well-known/oauth-protected-resource/api/v1`.



## OpenAPI

````yaml /api-reference/openapi.json get /api/cli/protected-resource
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:
  /api/cli/protected-resource:
    get:
      tags:
        - Sign-in
      summary: Protected resource metadata
      description: >-
        RFC 9728 protected resource metadata of `/api/v1`, also served at
        `/.well-known/oauth-protected-resource` (the URL every `/api/v1` 401
        names in `WWW-Authenticate: Bearer resource_metadata=…`) and
        `/.well-known/oauth-protected-resource/api/v1`.
      operationId: getProtectedResourceMetadata
      responses:
        '200':
          description: The resource, its authorization server and scopes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProtectedResourceMetadata'
      security: []
components:
  schemas:
    ProtectedResourceMetadata:
      type: object
      properties:
        resource:
          type: string
        resource_name:
          type: string
        resource_logo_uri:
          type: string
        resource_documentation:
          type: string
        authorization_servers:
          type: array
          items:
            type: string
        scopes_supported:
          type: array
          items:
            type: string
        bearer_methods_supported:
          type: array
          items:
            type: string
            enum:
              - header
      required:
        - resource
        - resource_name
        - resource_logo_uri
        - resource_documentation
        - authorization_servers
        - scopes_supported
        - bearer_methods_supported

````

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