openapi: 3.0.1
info:
  title: ClearVIN Vendor Authentication API
  description: REST API for ClearVIN's VIN decoding and vehicle history data. Clients exchange account credentials for a JWT bearer token at /rest/vendor/login, then request vehicle data by VIN from /rest/vendor/report. A single report endpoint returns VIN decode specifications, NMVTIS title and history data, and market valuation depending on the account subscription. Requests must originate from an IP address registered with ClearVIN. Documented endpoint paths are limited to login and report; additional product surfaces are served through the report endpoint.
  termsOfService: https://www.clearvin.com/en/terms-of-service/
  contact:
    name: ClearVIN
    url: https://www.clearvin.com/en/contact/
  version: '1.0'
servers:
- url: https://www.clearvin.com
  description: ClearVIN production API
tags:
- name: Authentication
paths:
  /rest/vendor/login:
    post:
      operationId: login
      tags:
      - Authentication
      summary: Authenticate and obtain a bearer token.
      description: Exchanges account email and password for a JWT bearer token that is valid for 120 minutes. The request must originate from an IP address registered with ClearVIN.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Authentication result with token on success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
components:
  schemas:
    LoginRequest:
      type: object
      required:
      - email
      - password
      properties:
        email:
          type: string
          format: email
          description: Account email address.
        password:
          type: string
          format: password
          description: Account password.
    LoginResponse:
      type: object
      properties:
        status:
          type: string
          description: Result status, "ok" on success or "error" on failure.
          enum:
          - ok
          - error
        message:
          type: string
          description: Error detail, present when status is "error".
        token:
          type: string
          description: JWT bearer token, present when status is "ok". Valid 120 minutes.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT obtained from /rest/vendor/login, sent as "Authorization: Bearer {token}". Tokens expire after 120 minutes.'