openapi: 3.1.0
info:
  title: Vessel CRM Accounts Authentication API
  description: The Vessel CRM API provides a unified interface for CRM operations across Salesforce, HubSpot, Zoho, Pipedrive, Close, Freshsales, Microsoft Dynamics, Affinity, monday.com, and Freshdesk. Operations are normalized across all CRM systems with consistent object models for contacts, deals, accounts, leads, notes, tasks, emails, calls, events, and users. Authentication uses vessel-api-token header and accessToken query parameter.
  version: '1.0'
  contact:
    name: Vessel Support
    email: support@vessel.dev
    url: https://www.vessel.dev/
  license:
    name: Proprietary
    url: https://www.vessel.dev/
servers:
- url: https://api.vessel.land
  description: Vessel CRM API
security:
- apiToken: []
tags:
- name: Authentication
paths:
  /link/token:
    post:
      operationId: createLinkToken
      summary: Create Link Token
      description: Creates a link token for initiating the Vessel Link authentication flow. Pass this token to the @vesselapi/react-vessel-link component to open the authentication modal.
      tags:
      - Authentication
      responses:
        '200':
          description: Link token created
          content:
            application/json:
              schema:
                type: object
                properties:
                  linkToken:
                    type: string
                    description: Temporary link token for authentication flow
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /link/exchange:
    post:
      operationId: exchangePublicToken
      summary: Exchange Public Token
      description: Exchanges a public token (returned from the Vessel Link UI after successful CRM authentication) for an access token and connection ID.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - publicToken
              properties:
                publicToken:
                  type: string
                  description: Public token from the Vessel Link UI onSuccess callback
      responses:
        '200':
          description: Tokens exchanged successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  connectionId:
                    type: string
                    description: Unique connection identifier
                  accessToken:
                    type: string
                    description: Access token for CRM API calls
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /auth/session-token:
    post:
      operationId: createSessionToken
      summary: Create Session Token
      description: Creates a temporary authentication session token. Call this endpoint each time a user wants to connect a new integration. The session token is passed to the Vessel client SDK to open the authentication modal.
      tags:
      - Authentication
      security:
      - apiToken: []
      responses:
        '200':
          description: Session token created
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      sessionToken:
                        type: string
                        description: Temporary session token for authentication flow
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
  /auth/access-token:
    post:
      operationId: exchangeAccessToken
      summary: Exchange Session Token for Access Token
      description: Exchanges a session token (returned from the Vessel client SDK after successful user authentication) for a permanent access token and connection ID. Store the access token securely on your backend.
      tags:
      - Authentication
      security:
      - apiToken: []
      - sessionToken: []
      responses:
        '200':
          description: Access token exchanged successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      accessToken:
                        type: string
                        description: Access token for making API calls on behalf of the user
                      connectionId:
                        type: string
                        description: Unique identifier for this user connection
                      integrationId:
                        type: string
                        description: Identifier for the connected integration
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
components:
  schemas:
    Error:
      type: object
      description: API error response
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
    Error_2:
      type: object
      description: API error response
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message
            code:
              type: string
              description: Error code identifier
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: vessel-api-token
      description: Your Vessel API token for server-side authentication