openapi: 3.0.3
info:
  title: Vagaro Enterprise Business API (Partial, Community-Modeled) Appointments Authentication API
  description: 'Vagaro publishes a "PUBLIC - Enterprise Business API V2" reference at docs.vagaro.com (readme.io). The Access Token endpoint below is transcribed directly from that public reference page: method, full path pattern, request body fields, and documented response codes. The Appointments, Customers, Employees, Employee Management, and Locations paths are honestly modeled from Vagaro''s own capability-level descriptions of those five areas ("retrieve details about appointments including status, start time, and service provider", "obtain customer contact information and tags", "view service provider details, contact information, and reporting relationships", "assign and unassign employees across locations with access levels, provision/deprovision calendars", "retrieve single or multi-location business details") and from the confirmed field names in Vagaro''s Webhook event payloads (Appointment, Customer, Employee, Business Location events). Exact parameter names, pagination style, and full response schemas for those five areas are not publicly visible without an approved Vagaro partner account and are marked x-endpointsModeled: true. Do not treat the modeled paths as verified against a live response.'
  version: v2
  contact:
    name: Vagaro
    url: https://www.vagaro.com/pro
  license:
    name: Proprietary
    url: https://docs.vagaro.com/
servers:
- url: https://api.vagaro.com/{region}/api/v2
  description: Vagaro Enterprise Business API (region-scoped)
  variables:
    region:
      default: us
      description: Business region assigned to the Vagaro account, as documented in the API basics guide.
security:
- bearerAuth: []
tags:
- name: Authentication
  description: Access token issuance for the Enterprise Business API.
paths:
  /merchants/generate-access-token:
    post:
      operationId: generateAccessToken
      tags:
      - Authentication
      summary: Generate an access token
      description: Exchanges a partner clientId and clientSecretKey, plus a comma- separated list of requested scopes, for a bearer access token. This endpoint, its method, and its path are transcribed from Vagaro's public reference page and are not modeled.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessTokenRequest'
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenResponse'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized - invalid clientId/clientSecretKey.
        '429':
          description: Too many requests.
components:
  schemas:
    AccessTokenResponse:
      type: object
      properties:
        accessToken:
          type: string
        tokenType:
          type: string
          example: Bearer
        expiresIn:
          type: integer
          description: Modeled - token lifetime in seconds; exact value not publicly confirmed.
        scope:
          type: string
    AccessTokenRequest:
      type: object
      required:
      - clientId
      - clientSecretKey
      - scope
      properties:
        clientId:
          type: string
          description: Unique client identifier issued when APIs & Webhooks access is approved.
        clientSecretKey:
          type: string
          description: Unique client secret issued alongside clientId.
        scope:
          type: string
          description: Comma-separated list of scopes; the required scope is listed on each API reference page.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token issued by /merchants/generate-access-token