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

> ## Agent Instructions
> To set up offstage cloud from a coding agent, read https://api.offstage.cloud/SKILL.md and follow it. The whole API guide is one file at https://api.offstage.cloud/llms.txt.

# Sign in

> Checks the email and password, sets the `oc_session` cookie for the user's own team (or their first team), and returns the user and that team. No credential needed.



## OpenAPI

````yaml /openapi.json post /v1/auth/login
openapi: 3.1.0
info:
  title: offstage cloud API
  version: 0.1.0
  summary: Real Macs for AI agents and CI, over HTTP.
  description: >-
    macOS sandboxes driven one call at a time, and fire-and-forget CI tasks, on
    Apple silicon Macs running macOS 27.


    - **Auth.** `Authorization: Bearer sk_offstage_…` (a team API key; one made
    before 2026-10-29 starts with `oc_live_` and still works), or the console's
    `oc_session` cookie. Operations marked `x-console-only: true` take only the
    cookie; an API key gets 403 `console-only`. A cookie request that changes
    something must come from this origin.

    - **Errors.** Every failure is `{"error": {"code", "message", "fix"?,
    "requestId"}}`. Switch on `code`; `fix`, when present, says what to do. Any
    operation can also answer 500 `internal` (a bug; quote the `requestId`), and
    an unknown route is 404 `no-such-route`.

    - **Request ids.** Every response carries an `x-request-id` header, repeated
    as `requestId` in error bodies.

    - **Units.** Times are Unix milliseconds, and durations end in `Ms`. Money
    is US dollars as numbers, exact to the micro-dollar (`costUsd`).

    - **Ids** are prefixed: `sbx_` sandbox, `cmd_` command, `run_` agent run,
    `task_` task, `key_` API key, `req_` request, `team_`, `usr_`, `box_` (a
    fleet Mac), `inv_`.

    - **Lists** are newest first. Pass the previous page's `nextCursor` as
    `cursor`; it is null on the last page.

    - **Bodies.** JSON, except file writes, which send raw bytes. Request
    schemas with `additionalProperties: false` refuse an unknown field with 400
    `unknown-field`.

    - **Limits.** A team may send 120 requests a minute, whatever key or session
    it uses. Every request also counts against its client address: 600 a minute,
    and far fewer on the routes that need no credential (5 sign-ups an hour, 20
    sign-ins and 20 verifications a minute). Over a window is 429 `rate-limit`
    with a `Retry-After` header.

    - **Verification.** A new account's team can sign in and look around, but
    cannot create sandboxes, tasks or API keys (403 `email-unverified`) until
    its owner opens the link emailed at signup.

    - **Holds.** No request is held longer than about 50 s, so default client
    timeouts and 60 s proxy idle timeouts are fine, except large files: a write
    answers once its upload is done, and a read streams for as long as the Mac
    takes to send it.


    The prose reference, with examples, is
    `https://api.offstage.cloud/llms.txt`. The agent setup guide is
    `https://api.offstage.cloud/SKILL.md`.
servers:
  - url: https://api.offstage.cloud
security:
  - apiKey: []
  - consoleSession: []
tags:
  - name: Sandboxes
    description: >-
      A Mac slot (a macOS user account) held for you: run commands, move files,
      take screenshots.
  - name: Tasks
    description: >-
      Fire-and-forget macOS work: clone a public repo, run a command, collect
      artifacts.
  - name: Recordings
    description: >-
      What a gui sandbox or gui task showed and did, kept by the plane: live
      while it runs, a replay after. Open one in the console at `/r/{id}`.
  - name: Capacity
    description: What the fleet can take right now, and whether the plane is up.
  - name: Billing
    description: The price, usage, the bill, the budget and the card.
  - name: Account
    description: Signing in, the team, its members and its API keys.
  - name: GitHub
    description: >-
      GitHub Actions jobs on offstage Macs: connect an organization in the
      console, then `runs-on: offstage-macos`.
  - name: Secrets
    description: Write-only team credentials selected by workload name.
paths:
  /v1/auth/login:
    post:
      tags:
        - Account
      summary: Sign in
      description: >-
        Checks the email and password, sets the `oc_session` cookie for the
        user's own team (or their first team), and returns the user and that
        team. No credential needed.
      operationId: login
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: The user and the team the session acts for.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            set-cookie:
              $ref: '#/components/headers/SetSession'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserAndTeam'
        '400':
          description: '`not-an-object`, `bad-email`, `missing-password`.'
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            `bad-credentials`: the email and password do not match an account.
            `no-team`: the account belongs to no team.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            `too-many-attempts` (with `Retry-After`): 10 failed sign-ins for
            this email from this address in 15 minutes, or one once the email
            has taken 50 from all addresses in 15 minutes. That address may try
            again 15 minutes after its first miss; an address with no misses at
            the email is not paused. A password reset or a GitHub or Google
            sign-in lifts every pause on the email. `rate-limit`: this address
            has tried to sign in 20 times in the last minute.
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security: []
components:
  schemas:
    LoginRequest:
      type: object
      properties:
        email:
          type: string
        password:
          type: string
      required:
        - email
        - password
      additionalProperties: true
    UserAndTeam:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
        team:
          $ref: '#/components/schemas/Team'
      required:
        - user
        - team
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                Stable and machine-readable, like `sandbox-closed`. Switch on
                this, not on the message.
            message:
              type: string
              description: What went wrong, for a person.
            fix:
              type: string
              description: What to do about it, when there is something to do.
            requestId:
              type: string
              description: >-
                The same as the `x-request-id` header. Quote it when asking for
                help.
              pattern: ^req_
          required:
            - code
            - message
            - requestId
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        The one error envelope: every 4xx and 5xx the plane itself sends. A
        proxy in front of it may send a 5xx whose body is not JSON.
      examples:
        - error:
            code: sandbox-closed
            message: sandbox sbx_mh3k2f9aQ1xYz0aBcDeFgHiJ is closed (idle)
            fix: create a new sandbox
            requestId: req_mh3k2f9aQ1xYz0aBcDeFgHiJ
    User:
      type: object
      properties:
        id:
          type: string
          description: '`usr_…`.'
          pattern: ^usr_
        email:
          type: string
        name:
          type: string
        createdAt:
          $ref: '#/components/schemas/Millis'
        emailVerified:
          type: boolean
          description: Whether they opened the verification link emailed at signup.
      required:
        - id
        - email
        - name
        - createdAt
        - emailVerified
      additionalProperties: false
    Team:
      type: object
      properties:
        id:
          type: string
          description: '`team_…`.'
          pattern: ^team_
        name:
          type: string
        slug:
          type: string
        createdAt:
          $ref: '#/components/schemas/Millis'
        verified:
          type: boolean
          description: >-
            Whether the team may run work and make keys: its owner verified
            their email. False only for a new team until then.
        kind:
          type: string
          enum:
            - personal
            - organization
          description: >-
            `personal`: the team signing up made, which holds one person and
            invites nobody. `organization`: made with POST /v1/teams to share.
        region:
          type: string
          enum:
            - us
          description: Where the team's Macs run. `us` only for now.
      required:
        - id
        - name
        - slug
        - createdAt
        - verified
        - kind
        - region
      additionalProperties: false
    Millis:
      type: integer
      minimum: 0
      description: A time, in Unix milliseconds.
  headers:
    RequestId:
      description: This request's id, `req_…`. Quote it when asking for help.
      required: true
      schema:
        type: string
        pattern: ^req_
    SetSession:
      description: Sets the `oc_session` cookie.
      schema:
        type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        A team API key, `sk_offstage_…`, created in the console. Everything it
        touches belongs to its team.
    consoleSession:
      type: apiKey
      in: cookie
      name: oc_session
      description: >-
        The console's session cookie (httpOnly, SameSite=Lax, 30 days), set by
        `signup` and `login`.

````

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