Yubico Web Service API

---

The Yubico Web Service APIs makes it possible for you to verify the one-time passwords (OTP) generated by the YubiKey. This page describes how to get started working with our server, and also provides the protocol specification.

We have written clients in several languages and for different purposes, so chances are that you do not need to implement our protocol yourself. Save your time and look at our existing clients: Java, C#/.NET, Python, PHP, Ruby.

If you write a new client following these specifications, please let us know so that others can avoid duplicating work.

To get a real-time understanding of the protocol, you may use the Auth_Yubico PHP demo page:
» Yubico API demo

---

Getting started

Here is the quickest way to get started:

1. API key

API key is used to optionally sign the OTP validation request and to verify the OTP validation response. We recommend all production deployments use either API key or HTTPS.

If you use HTTPS to access Yubico's validation web service and you validate the Yubico server SSL certificate, you don't need to use the shared key to further authenticate response signatures from Yubico.

If you for some reason do not want to rely on HTTPS. You may also sign requests using this API key.

To get an API key, first use our online API key generator. It will assign you an ID and create a shared key. You can use the shared key to authenticate that the API responses do come from Yubico.

2. Capture an OTP

Capture an OTP output from your YubiKey. You can do that by opening Notepad (for Windows), TextEdit (for Mac OS X) or Emacs (for GNU/Linux) and simply pressing the button on the YubiKey. The OTP is a simple string of characters, like this: vvvvvvcurikvhjcvnlnbecbkubjvuittbifhndhn.

3. Send OTP to our server

Make the authentication request against our server following the protocol specified below. Your request should include the verifier ID, a number that identifies the approver of your key, and the OTP you captured in the previous instruction. The request is part of the HTTP GET URL, encoded using normal parameter/value pairs. For example (broken into two lines for legibility):

http://api.yubico.com/wsapi/verify?id=42&otp=vvvvvvcur\
ikvhjcvnlnbecbkubjvuittbifhndhn

4. Parse response

You will recieve a response back from the server, a string of text that resembles the following:

h=hhbVQZYvkEWUdhYjx1hjB/yeW/Y=
t=2008-01-11T03:51:21Z0079
status=OK

You can check the authenticity of this response using the HMAC specification detailed below.

5. Make a decision

Do what you wish with the information in the response, specifically the section denoted with "status=" as this is the final response. All our APIs define constants related to these statuses, also listed below.

---



Protocol Specification

All requests are HTTP GETs. As such, all parameters must be properly URL encoded. In particular, some base64 characters (such as "+") in the value fields needs to be escaped.

Each response sent by Yubico is signed. To make sure the response has not been tampered with, you should verify the signature.

To verify a signature on a response message, follow the same procedure that was used to sign the response message and compare the signature in the response to the signature you generated. If the signature values are equal, the signature is correct.

Make sure you remove the signature itself from the values you generate the signature over for verification. If the incoming message is

b=1&a=2&c=3&h=V5FkMYr9GCG9tQA9ihuuybWl99U=

make sure to remove h before verifying:

b=1&a=2&c=3 

---

Generating signatures

The Yubico API uses HMAC-SHA1 signatures with 160 bit key lengths (as defined by RFC 3174). The HMAC key to use is the API key.

Generate the signature over the parameters in the message. Each message contains a set of key/value pairs, and the signature is always over the entire set (excluding the signature itself), sorted in alphabetical order of the keys. To generate a message signature:

1. Alphabetically sort the set of key/value pairs by key order.
2. Construct a single line with each ordered key/value pair concatenated using '&', and each key and value contatenated with '='. Do not add any linebreaks. Do not add whitespace. For example: a=2&b=1&c=3.
3. Apply the signature algorithm to the line's octet string (UTF-8 byte values according to RFC 3629) using the API key as key.
4. Base 64 encode the resulting value according to RFC 4648, for example, t2ZMtKeValdA+H0jVpj3LIichn4=.
5. Append the value under key h to the message.

---

Verification

There is one call to verify YubiKey OTPs: verify.

verify The verify call lets you check whether an OTP is valid. Since the OTP itself contains identification information, all you have to do is to send the OTP.

---

Request

Construct an HTTP GET call to

http://api.yubico.com/wsapi/verify

with the following parameters (note that this request need not be signed):

parameter	type	required	purpose
id	string	Yes	Specifies the requestor so that the end-point can retrieve correct shared secret for signing the response.
otp	string	Yes	The OTP from the YubiKey.
timestamp	string	No	Timestamp=1 requests timestamp and session counter information the response
h	string	No	The optional HMAC-SHA1 signature for the request.

An example request (broken into two lines for legibility):

http://api.yubico.com/wsapi/verify?otp=vvvvvvcucrlcietctc\
kflvnncdgckubflugerlnr&id=87 

And if you require additional information on timestamp and session counters:

http://api.yubico.com/wsapi/verify?otp=vvvvvvcucrlcietctc\
kflvnncdgckubflugerlnr&id=87×tamp=1 

---

Response

The verification response tells you whether the OTP is valid.

The response has the following values:

parameter	type	purpose
h	string (base64)	Signature as described above.
t	time stamp	Timestamp in UTC.
status	string	The status of the operation. The status are described in return codes.
timestamp	string	YubiKey internal timestamp value when key was pressed
sessioncounter	string	YubiKey internal usage counter when key was pressed
sessionuse	string	YubiKey internal session usage counter when key was pressed

---

Return codes

These are possible status values in a verify response:

name	meaning
OK	The OTP is valid.
BAD_OTP	The OTP is invalid format.
REPLAYED_OTP	The OTP has already been seen by the service.
BAD_SIGNATURE	The HMAC signature verification failed.
MISSING_PARAMETER	The request lacks a parameter.
NO_SUCH_CLIENT	The request id does not exist.
OPERATION_NOT_ALLOWED	The request id is not allowed to verify OTPs.
BACKEND_ERROR	Unexpected error in our server. Please contact us if you see this error.