openapi: 3.1.0
info:
  title: Convex Deployment Platform AccessTokens API
  description: The Convex Deployment Platform API is a deployment-scoped administrative REST API for configuring individual Convex deployments. It exposes private endpoints accessible only to deployment administrators and supports operations such as managing environment variables and other deployment configuration settings. Each deployment has its own endpoint in the format https://{deployment-name}.convex.cloud/api/v1/. Authentication requires an Authorization header using deployment keys, Team Access Tokens, or OAuth Application Tokens formatted as "Convex {token}". This API is currently in Beta and is intended for platform integrations and infrastructure automation workflows.
  version: v1-beta
  contact:
    name: Convex Platform Support
    email: platforms@convex.dev
    url: https://www.convex.dev/community
  termsOfService: https://www.convex.dev/terms
servers:
- url: https://{deploymentName}.convex.cloud/api/v1
  description: Convex Deployment Server
  variables:
    deploymentName:
      default: happy-otter-123
      description: The deployment name found in the Convex dashboard or via the Management API. Each deployment has a unique subdomain under convex.cloud.
security:
- convexAuth: []
tags:
- name: AccessTokens
  description: Create and manage Team Access Tokens used for authenticating Management API requests on behalf of a team.
paths:
  /teams/{team_id}/create_access_token:
    post:
      operationId: createAccessToken
      summary: Create a team access token
      description: Creates a new Team Access Token for the specified team. Team Access Tokens are used to authenticate Management API requests and grant access to all projects and deployments within the team. The token value is only returned at creation time and should be stored securely.
      tags:
      - AccessTokens
      parameters:
      - $ref: '#/components/parameters/teamId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAccessTokenRequest'
      responses:
        '200':
          description: Access token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessToken'
        '401':
          description: Unauthorized — missing or invalid token
components:
  schemas:
    CreateAccessTokenRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Human-readable name for the access token.
    AccessToken:
      type: object
      required:
      - name
      - token
      properties:
        name:
          type: string
          description: Human-readable name of the access token.
        token:
          type: string
          description: The token value used for API authentication. Only returned at creation time; store it securely as it cannot be retrieved later.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the token was created.
  parameters:
    teamId:
      name: team_id
      in: path
      required: true
      description: The integer identifier of the Convex team. Available in the Convex dashboard when creating Team Access Tokens.
      schema:
        type: integer
        format: int64
  securitySchemes:
    convexAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Authorization header using a deployment key, Team Access Token, or OAuth Application Token. The token must be prefixed with the string "Convex " (e.g. "Authorization: Convex prod:abc123..."). Deployment keys are created in the dashboard or via the Management API.'
externalDocs:
  description: Convex Deployment Platform API Documentation
  url: https://docs.convex.dev/deployment-platform-api