YubiAuth REST API

All responses are formatted as JSON. Note that the URLs given in this document assume standard endpoints, but depending on the configuration of your settings, these may differ. There are two separate REST APIs available, the Core API and the Client API.

Core API

The core API grants complete administrative powers with the ability to create and modify users, Yubikeys, attributes, etc. This API should never be publically exposed.

Users

Users each have a unique user ID as well as a unique username. Each user has a password, and may have zero or more YubiKeys assigned to them. Users can have Attributes.

Create a user

Resource
POST http://<host>/core/users
Request

Parameters

username

A unique username (required)

password

The password to give to the user (required)

Example

curl http://127.0.0.1:8080/core/core/users --data "username=trillian&password=foobar"
Response

Returns a 201 Created response, with a Location header pointing to the created resource, as well as a JSON body containing the user ID and username:

{"id": 41, "name": "trillian"}

Listing users

Resource
GET http://<host>/core/users
Request

Query parameters can optionally be provided to filter users by their Attributes, or by their assigned YubiKeys. Only users matching the filters are shown.

Example

curl http://127.0.0.1:8080/core/users?yubikey=ccccccccccce
Response

Returns a list of user IDs and usernames, for example:

[
  { 'id': 42, 'name': 'zaphod' },
  { 'id': 43, 'name': 'ford' }
]

View a user

Resource
GET http://<host>/core/users/<id-or-username>
Request

A user can be uniquely identified by either the user ID or by the username.

Example

curl http://127.0.0.1:8080/core/users/43

or

curl http://127.0.0.1:8080/core/users/ford
Response

Returns a JSON representation of the user:

{
  "attributes": {
    "full_name": "Ford Prefect"
  },
  "yubikeys": ["ccccccccccce"],
  "id": 43,
  "name": "ford"
}

Deleting a user

Resource
DELETE http://<host>/core/users/<id-or-username>

or

POST http://<host>/core/users/<id-or-username>/delete
Request

Deleting a user is done by sending a DELETE request to the user. To accomodate browsers that do not support this, an alternative is available which uses POST.

Example

curl -X DELETE http://127.0.0.1:8080/core/users/41

or

curl -X POST http://127.0.0.1:8080/core/users/41/delete
Response

Returns an empty response with status 204 No Content on success.

(Re-) Setting a users password

Resource
POST http://<host>/core/users/<id-or-username>/reset
Request

Parameters

password: The users new password (required)

Example

curl http://127.0.0.1:8080/core/users/41/reset --data "password=newpass"
Response

Returns an empty response with status 204 No Content on success.

Validating a users password and/or YubiKey OTP

Checks if a given password and/or YubiKey OTP (One Time Password) is valid for the user.

Resource
GET or POST http://<host>/core/users/<id-or-username>/validate
Request

Parameters

password

The value of the attribute to set (optional)

otp

The value of the attribute to set (optional)

Example

curl http://127.0.0.1:8080/core/users/41/validatepassword=foo&otp=ccccccccccceglgvbrbttbctichrejkvbjbgigetfgkr
Response

A JSON object containing "valid_password" and "valid_otp" keys, each mapping to either true or false. For example:

{
  "valid_password": true,
  "valid_otp": false
}

YubiKeys

YubiKeys are identified by their unique prefixes. Each YubiKey can be assigned to zero or more Users, and can be enabled or disabled. Each YubiKey can have Attributes.

Assigning a YubiKey to a User

Resource
POST http://<host>/core/user/<id-or-username>/yubikeys
Request

Parameters

yubikey

The prefix of the YubiKey to assign (required)

Example

curl http://127.0.0.1:8080/core/users/1/yubikeys --data "yubikey=ccccccccccce"
Response

Returns an empty response with status 204 No Content on success.

View a YubiKey

Resource
GET http://<host>/core/user/<id-or-username>/yubikeys/<prefix>

or

GET http://<host>/core/yubikeys/<prefix>
Request

A YubiKey can be accessed either via a user to which is is assigned, or directly via its prefix alone. Note that trying to access an existing YubiKey (correct prefix) via a user to which it is NOT assigned will result in a 404 Not Found.

Example

curl http://127.0.0.1:8080/core/users/1/yubikeys/ccccccccccce

or

curl http://127.0.0.1:8080/core/yubikeys/ccccccccccce
Response

Returns a JSON representation of the YubiKey:

{
  "attributes": {},
  "prefix": "ccccccccccce",
  "enabled": true,
  "id": 53
}

Unassigning a YubiKey for a User

Resource
DELETE http://<host>/core/user/<id-or-username>/yubikeys/<prefix>

or

POST http://<host>/core/user/<id-or-username>/yubikeys/<prefix>/delete
Request

Unassigning a YubiKey for a User to which it is assigned is done by sending a HTTP DELETE request to it. NOTE that the YubiKey will still exist in the system retaining its enabled state as well as any attributes. A POST alternative is available.

Example

curl -X DELETE http://127.0.0.1:8080/core/users/41/yubikeys/ccccccccccce

or

curl -X POST http://127.0.0.1:8080/core/users/41/yubikeys/ccccccccccce/delete
Response

Returns an empty response with status 204 No Content on success.

Deleting a YubiKey

Resource
DELETE http://<host>/core/yubikeys/<prefix>

or

POST http://<host>/core/yubikeys/<prefix>/delete
Request

Deleting a YubiKey removes it together with any data it holds from the system, as well as removing any assignment to it any Users may have.

Example

curl -X DELETE http://127.0.0.1:8080/core/yubikeys/ccccccccccce

or

curl -X POST http://127.0.0.1:8080/core/yubikeys/ccccccccccce/delete
Response

Returns an empty response with status 204 No Content on success.

Attributes

Both Users and YubiKeys have attributes. These are accessed by taking the path of the user or YubiKey and appending "/attributes" to the end, for example:

http://127.0.0.1:8080/core/users/42/attributes

or

http://127.0.0.1:8080/core/yubikeys/cccccccccccd/attributes

or

http://127.0.0.1:8080/core/users/42/yubikeys/cccccccccccd/attributes

In the following requests, any of the above formats qualify as attribute_base.

View attributes

Resource
GET http://<host>/core/<attribute_base>
Request

Example

curl http://127.0.0.1:8080/core/users/42/attributes
Response

A JSON object with key-values matching the attributes.

{
  "full_name": "Ford Prefect"
  "email": "ford@example.com",
}

Set attribute

Sets the value of an attribute. If the attribute already exists, it will be overwritten.

Resource
POST http://<host>/core/<attribute_base>
Request

Parameters

key

The key of the attribute to set (required)

value

The value of the attribute to set (required)

Example

curl http://127.0.0.1:8080/core/users/42/attributes --data "key=email&value=ford@example.com"
Response

Returns an empty response with status 204 No Content on success.

Get attribute

Gets the value of a single attribute.

Resource
GET http://<host>/core/<attribute_base>/<key>
Request

Example

curl http://127.0.0.1:8080/core/users/42/attributes/email
Response

A JSON string, or null, for example:

"ford@example.com"

Unset/Delete attribute

Removes an attribute, if it exists.

Resource
DELETE http://<host>/core/<attribute_base>/<key>

or

POST http://<host>/core/<attribute_base>/<key>/delete
Request

Attributes are removed by sending a HTTP DELETE request (POST alternative available).

Example

curl -X DELETE http://127.0.0.1:8080/core/users/42/attributes/email
Response

Returns an empty response with status 204 No Content.

Client API

The client API provides user authentication and modification of individual users, as well as session management. This API can be used by clients wishing to administer a single users password and yubikeys. Many of the actions require a valid session for the user on which to perform the action.

Authentication

Validate user credentials. Also see Validating a users password and/or YubiKey under Users in the Core API.

Authenticate a user

Checks if the provided credentials are valid and sufficient to authenticate a user. The username may be omitted if the server allows OTP based user identification, and a valid OTP is provided.

Resource
GET or POST http://<host>/client/authenticate
Request

Parameters

username

The username of the user to authenticate (optional)

password

The users password (optional)

otp

A valid OTP from a YubiKey that is assigned to the user (optional)

Example

curl http://127.0.0.1:8080/client/authenticate --data "username=trillian&password=foo"
Response

Returns a JSON boolean true value if the given parameters are valid and sufficient to authenticate the given user, false otherwise.

Sessions

Create, view and destroy user sessions. Creating a session results in a session cookie which must been included in requests for actions requiring a session. The cookie may be passed in cookie form, or alternatively, in the X-YubiAuth-Session HTTP header. Calling a resource that requires a valid session without a valid session cookie will result in an error. For example:

{
  "error": "Session required!"
}

Create a session

Creates a new session for the given user, returning a session cookie.

Resource
GET or POST http://<host>/client/login
Request

Parameters

username

The username of the user to authenticate (optional)

password

The users password (optional)

otp

A valid OTP from a YubiKey that is assigned to the user (optional)

Example

curl http://127.0.0.1:8080/client/login --data "username=trillian&password=foo"
Response

Returns a JSON object containing a session cookie if the given parameters are valid and sufficient to authenticate the given user. Returns an error otherwise. For example:

{
  "session": "6cfba105278bb491c35aaffe727df40664265b27d3ffe472638540bf91af73f77884be55"
}

Besides returning the cookie in the JSON response, the HTTP response will set the session cookie as a HTTP cookie.

Destroy a session

Resource
GET or POST http://<host>/client/logout
Request

Requires valid session

Example

curl http://127.0.0.1:8080/client/logout -H "X-YubiAuth-Session: 6cfb...be55"
Response

Invalidates the session and returns a JSON boolean true value if the given session cookie was valid. Returns an error otherwise.

Get the status of a session

Resource
GET or POST http://<host>/client/status
Request

Requires valid session

Example

curl http://127.0.0.1:8080/client/status -H "X-YubiAuth-Session: 6cfb...be55"
Response

Returns a JSON object with information about the user if the given session cookie was valid. Returns an error otherwise. For example:

{
  "username": "trillian",
  "user_id": 41,
  "prefix": "ccccccccccce",
  "_accessed_time": 1426068715.018119,
  "_creation_time": 1426068593.186552
}

Change the users password

Sets a new password for the authenticated uses. This requires the caller to provide authentication again, in the form of the current password and a new OTP (if applicable).

Resource
GET or POST http://<host>/client/password
Request

Requires valid session

Parameters

newpass

The new password to set for the user (required)

oldpass

The current password of the user (optional)

otp

A valid OTP from a YubiKey that is assigned to the user (optional)

Example

curl http://127.0.0.1:8080/client/password -d''
Response

Returns a JSON boolean true value if successful.

Note
This API is not fully documented.