Yubico Validation API

openapi: 3.1.0
info:
  title: Yubico YubiCloud OTP Validation API
  version: '2.0'
  description: YubiCloud is Yubico's hosted web service for verifying Yubico One-Time Passwords (OTPs) generated by a YubiKey. A client submits an OTP to the verify endpoint and receives a signed plain-text response indicating whether the OTP is valid. Since 2020 all validation traffic is served from the single endpoint api.yubico.com. Requests and responses are authenticated with an HMAC-SHA1 signature computed over a shared secret obtained with the free API key (Client ID). Responses are newline-delimited key=value pairs, not JSON.
  contact:
    name: Yubico Developer Program
    url: https://developers.yubico.com/
  termsOfService: https://www.yubico.com/support/terms-conditions/
  license:
    name: Yubico Terms & Conditions
    url: https://www.yubico.com/support/terms-conditions/
  x-source: https://developers.yubico.com/Software_Projects/YubiCloud_REST_API.html
  x-captured-by: api-evangelist-enrichment
  x-capture-method: generated-from-docs-and-live-probe
servers:
- url: https://api.yubico.com/wsapi/2.0
  description: YubiCloud production validation endpoint
security:
- clientSignature: []
tags:
- name: Validation
  description: Yubico OTP validation operations.
paths:
  /verify:
    get:
      operationId: verifyOtp
      summary: Verify a Yubico OTP
      description: Validate a 44-character ModHex Yubico OTP against YubiCloud. The service returns a signed status indicating whether the OTP is valid, replayed, or malformed. Always verify the response signature (h) and confirm the returned nonce matches the nonce that was sent.
      tags:
      - Validation
      parameters:
      - name: id
        in: query
        required: true
        description: Numeric Client ID obtained from the Yubico API key generator.
        schema:
          type: string
          example: '12345'
      - name: otp
        in: query
        required: true
        description: The 44-character ModHex-encoded OTP emitted by the YubiKey.
        schema:
          type: string
          minLength: 32
          maxLength: 48
          example: cccccccccccccccccccccccccccccccccccccccccccc
      - name: nonce
        in: query
        required: true
        description: Unique random string of 16 to 40 alphanumeric characters, used to protect against replay of the request/response pair.
        schema:
          type: string
          minLength: 16
          maxLength: 40
          pattern: ^[A-Za-z0-9]{16,40}$
      - name: h
        in: query
        required: false
        description: Optional Base64-encoded HMAC-SHA1 signature of the request parameters using the client's shared secret. Recommended for production.
        schema:
          type: string
      - name: timestamp
        in: query
        required: false
        description: Set to 1 to request the YubiKey internal timestamp and session counters in the response.
        schema:
          type: integer
          enum:
          - 0
          - 1
      - name: sl
        in: query
        required: false
        description: Requested percentage of syncing servers that must agree before a response is returned. Integer 0-100 or the strings "fast" or "secure".
        schema:
          type: string
      - name: timeout
        in: query
        required: false
        description: Number of seconds to wait for sync responses before returning.
        schema:
          type: integer
      responses:
        '200':
          description: A signed plain-text response. The overall outcome is carried in the status field; the HTTP status is 200 even for invalid OTPs.
          content:
            text/plain:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
              examples:
                badOtp:
                  summary: Live BAD_OTP response
                  value: 'h=hpWWH9kBIw99VSocLFQ8IVW6tKs=

                    t=2026-07-22T00:56:42Z0511

                    otp=cccccccccccccccccccccccccccccccccccccccccccc

                    nonce=abcdefghijklmnop

                    status=BAD_OTP

                    '
components:
  schemas:
    ValidationResponse:
      type: object
      description: Newline-delimited key=value fields returned by YubiCloud.
      properties:
        h:
          type: string
          description: Base64 HMAC-SHA1 signature of the response fields.
        t:
          type: string
          description: Server timestamp in UTC (ISO 8601 with server counter suffix).
        otp:
          type: string
          description: Echoed OTP from the request.
        nonce:
          type: string
          description: Echoed nonce from the request; must match what was sent.
        status:
          $ref: '#/components/schemas/ValidationStatus'
        timestamp:
          type: string
          description: YubiKey internal timestamp (only when timestamp=1 requested).
        sessioncounter:
          type: string
          description: YubiKey usage/session counter (only when timestamp=1 requested).
        sessionuse:
          type: string
          description: YubiKey session use counter (only when timestamp=1 requested).
        sl:
          type: string
          description: Percentage of syncing servers that replied.
      required:
      - h
      - t
      - otp
      - nonce
      - status
    ValidationStatus:
      type: string
      description: Outcome of the OTP validation.
      enum:
      - OK
      - BAD_OTP
      - REPLAYED_OTP
      - BAD_SIGNATURE
      - MISSING_PARAMETER
      - NO_SUCH_CLIENT
      - OPERATION_NOT_ALLOWED
      - BACKEND_ERROR
      - NOT_ENOUGH_ANSWERS
      - REPLAYED_REQUEST
  securitySchemes:
    clientSignature:
      type: apiKey
      in: query
      name: id
      description: Numeric Client ID plus an HMAC-SHA1 signature (h) computed over the request parameters with the shared secret issued alongside the Client ID.