Automo OAuth API

openapi: 3.2.0
info:
  title: Automo Build OAuth API
  version: 1.3.0
  description: 'The machine surface of Automo Build, the AI app builder. All capability calls go through the MCP endpoint (Model Context Protocol, Streamable HTTP): tools are discovered live via tools/list after OAuth sign-in. This document describes that endpoint, the OAuth 2.1 authorization server that protects it, and the discovery documents around them. Start at the server card or the protected-resource metadata; the site overview for agents is https://automo.build/llms.txt; agent registration is walked through at https://automo.build/auth.md.


    Rate limits: the unauthenticated endpoints answer with RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds), counted per client IP. MCP tool calls carry the same headers for the connection''s read, write or spawn budget. Past the limit the answer is 429 with Retry-After.


    Idempotency: POST /agent/identity accepts an Idempotency-Key header (16 to 255 printable characters, a UUID is ideal). A retry with the same key and body answers about the same registration instead of opening a second one; the same key with a different body is refused with 422.


    Versioning and deprecation: the MCP endpoint is versioned by the MCP-Protocol-Version header, whose values are MCP revision dates; every revision listed for it is served from the same URL. info.version follows semantic versioning: additions bump the minor version, breaking changes the major. Before a protocol revision or an operation is removed it is marked deprecated in this document and its responses carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers for at least 90 days.'
  contact:
    name: Automo Build
    url: https://automo.build/contact
    email: support@automo.ai
servers:
- url: https://mcp.automo.build
security:
- oauth2:
  - workspaces:read
  - projects:read
  - projects:write
  - prompts:write
  - sessions:read
  - sessions:write
  - reviews:read
  - reviews:write
  - playbooks:read
  - playbooks:run
  - playbooks:write
  - deployments:read
  - deployments:write
  - chat:read
  - billing:write
tags:
- name: OAuth
paths:
  /oauth/authorize:
    get:
      operationId: authorize
      summary: OAuth 2.1 authorization endpoint
      description: Authorization code with PKCE. The client_id is an HTTPS Client ID Metadata Document URL. The person consents on app.automo.build; the code returns to redirect_uri.
      parameters:
      - name: response_type
        in: query
        required: true
        schema:
          type: string
          const: code
      - name: client_id
        in: query
        required: true
        schema:
          type: string
          format: uri
      - name: redirect_uri
        in: query
        required: true
        schema:
          type: string
          format: uri
      - name: scope
        in: query
        required: false
        schema:
          type: string
      - name: state
        in: query
        required: false
        schema:
          type: string
      - name: code_challenge
        in: query
        required: true
        schema:
          type: string
      - name: code_challenge_method
        in: query
        required: true
        schema:
          type: string
          const: S256
      - name: resource
        in: query
        required: false
        schema:
          type: string
          format: uri
      responses:
        '302':
          description: Redirect to consent, then to redirect_uri with code and iss
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
      - OAuth
  /oauth/token:
    post:
      operationId: token
      summary: OAuth 2.1 token endpoint
      description: 'Code exchange and refresh, plus the two agent-registration grants: jwt-bearer exchanges an identity_assertion, and the claim grant is polled with a claim_token (authorization_pending, then slow_down if polled faster than the interval) until the user confirms.'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                  - authorization_code
                  - refresh_token
                  - urn:ietf:params:oauth:grant-type:jwt-bearer
                  - urn:workos:agent-auth:grant-type:claim
                code:
                  type: string
                redirect_uri:
                  type: string
                  format: uri
                client_id:
                  type: string
                code_verifier:
                  type: string
                refresh_token:
                  type: string
                resource:
                  type: string
                  format: uri
                assertion:
                  type: string
                  description: 'jwt-bearer grant: the identity_assertion from registration'
                claim_token:
                  type: string
                  description: 'claim grant: poll until the user confirms'
              required:
              - grant_type
      responses:
        '200':
          description: Access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '400':
          description: invalid_grant, authorization_pending, slow_down and friends
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthError'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
      - OAuth
  /oauth/revoke:
    post:
      operationId: revoke
      summary: RFC 7009 revocation endpoint
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                token:
                  type: string
                token_type_hint:
                  type: string
                  enum:
                  - access_token
                  - refresh_token
              required:
              - token
      responses:
        '200':
          description: Revoked (also for unknown tokens, per RFC 7009)
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimitPolicy'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
      - OAuth
components:
  headers:
    RateLimitReset:
      description: Seconds until the window frees a request
      schema:
        type: integer
    RetryAfter:
      description: Seconds to wait before retrying
      schema:
        type: integer
    RateLimitLimit:
      description: Requests allowed in the current window
      schema:
        type: integer
    RateLimitPolicy:
      description: The limit and its window, as "<limit>;w=<seconds>"
      schema:
        type: string
    RateLimitRemaining:
      description: Requests left in the current window
      schema:
        type: integer
  responses:
    TooManyRequests:
      description: Rate limited; wait Retry-After seconds
      headers:
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OAuthError'
  schemas:
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: JWT, ES256, one hour
        token_type:
          type: string
          const: Bearer
        expires_in:
          type: integer
        refresh_token:
          type: string
          description: Opaque, single-use, rotates on refresh
        scope:
          type: string
          description: Space-separated granted scopes
        identity_assertion:
          type: string
          description: 'Claim grant only: the assertion for later jwt-bearer sign-ins'
        assertion_expires:
          type: string
          format: date-time
      required:
      - access_token
      - token_type
      - expires_in
    OAuthError:
      type: object
      description: RFC 6749 error body
      properties:
        error:
          type: string
        error_description:
          type: string
      required:
      - error
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Automo Build OAuth 2.1: authorization code with PKCE (S256). Clients register by Client ID Metadata Document (the client_id is an HTTPS URL); there is no dynamic client registration. Tokens are JWTs bound to the resource URL, one hour, with rotating refresh tokens.'
      flows:
        authorizationCode:
          authorizationUrl: https://mcp.automo.build/oauth/authorize
          tokenUrl: https://mcp.automo.build/oauth/token
          refreshUrl: https://mcp.automo.build/oauth/token
          scopes:
            workspaces:read: List workspace memberships, whoami, switch the current workspace
            projects:read: List and search projects, project status, env var names, screenshots, deployment history
            projects:write: Create projects, wake sandboxes, share and clone links
            prompts:write: Prompt a project's main agent
            sessions:read: Read any agent session the user can read in the app
            sessions:write: Open, continue and stop agent sessions (CTO, Doctor, Security, QA, Architect, builder spawns)
            reviews:read: 'The sign-off state of builder work: cards, verdicts, fixes, whose move it is'
            reviews:write: Promote, ask a reviewer, hand fixes to the builder, approve or cancel a review
            playbooks:read: List playbooks and read their runs
            playbooks:run: Run a playbook
            playbooks:write: Create and edit playbooks
            deployments:read: Pending publish, deployment status and history
            deployments:write: Propose and approve deployments, publish
            chat:read: Read project chat history
            billing:write: Put a workspace on the Free plan