1. Home
  2. Software Projects
  3. YubiCloud REST API

    YubiCloud REST API

    The YubiCloud provides a secure, scalable, and globally distributed service for validating One-Time Passwords (OTPs) generated by YubiKeys. The simple RESTful API is the recommended method for all modern OTP integrations.

    This guide provides the essential details for validating a YubiKey OTP from your application.

    API Endpoint Details

    The API is accessed via a simple HTTPS GET request.

    • Method: GET

    • Endpoint URL: https://api.yubico.com/wsapi/2.0/verify

    • Protocol: HTTPS

    • Response Format: Newline-delimited key-value pairs (key=value\n...)

    Authentication: Getting an API Key

    Before you can use the YubiCloud API, you must obtain a Client ID. An optional API Key can also be generated if you wish to sign your requests for added security.

    Making a Validation Request

    A validation request is an HTTPS GET call to the verify endpoint containing the three required query parameters: id, otp, and nonce.

    Request Parameters

    Parameter Description Required?

    id

    		 
    Your numeric Client ID obtained from the API key generator.
    		 
    **Yes**

    otp

    		 
    The 44-character ModHex encoded One-Time Password generated by a YubiKey.
    		 
    **Yes**

    nonce

    		 
    A unique, random string (16-40 alphanumeric characters) generated by your client for this request. It is a critical security measure to prevent replay attacks and ensure response integrity.
    		 
    **Yes**

    Example Request with curl

    This curl example shows a valid request, including the required nonce and proper quoting for the URL.

    # Generate a random 32-character nonce for this request.
# In a real application, this should be a cryptographically secure random string.
NONCE=$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32)

# Press your YubiKey to generate a fresh OTP.
# Replace <YOUR_CLIENT_ID> and <YOUR_YUBIKEY_OTP> with your values.
curl 'https://api.yubico.com/wsapi/2.0/verify?id=<YOUR_CLIENT_ID>&nonce='${NONCE}'&otp=<YOUR_YUBIKEY_OTP>'

    Handling the API Response

    The API response is a plain-text, newline-separated list of key-value pairs. Your application should parse this response and, most importantly, check that the status field is exactly OK.

    Successful Response (status=OK)

    If the OTP is valid, the API will return status=OK along with your original nonce.

    Example Successful Response
    h=lR22a1+aZ55S/xVvG3S3AsFG2/c=
t=2025-06-05T20:55:10Z0814
otp=vvcijgklnrbfditdennrucunkbthghhbbgelblvifgkn
nonce=aeBieT6Nake2i4N4iim7sheeChii6u4V
sl=100
status=OK

    Always verify the signature (h=...) and that the returned nonce matches the one you sent in a production environment to ensure the response is authentic and belongs to your request.

    Common Error Statuses

    Status Value Meaning

    BAD_OTP

    		 
    The OTP is invalid.

    REPLAYED_OTP

    		 
    The OTP has already been seen by the validation server.

    BAD_SIGNATURE

    		 
    The request was signed with an API key, but the signature was invalid.

    MISSING_PARAMETER

    		 
    One of the required parameters (`id`, `otp`, or `nonce`) was missing from the request.

    NO_SUCH_CLIENT

    		 
    The Client ID (`id=...`) does not exist.

    BACKEND_ERROR

    		 
    An unexpected error occurred on the YubiCloud server. Your client should retry later.

    Next Steps & Official Documentation

    For more advanced topics like signing requests, response signature validation, and running your own validation server, please refer to the official Yubico OTP documentation.