{"id": 41, "name": "trillian"}
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.
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 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.
POST http://<host>/core/users
Parameters
username
|
A unique username |
password
|
The password to give to the user |
Example
curl http://127.0.0.1:8080/core/core/users --data "username=trillian&password=foobar"
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"}
GET http://<host>/core/users
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
Returns a list of user IDs and usernames, for example:
[
{ 'id': 42, 'name': 'zaphod' },
{ 'id': 43, 'name': 'ford' }
]
GET http://<host>/core/users/<id-or-username>
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
Returns a JSON representation of the user:
{
"attributes": {
"full_name": "Ford Prefect"
},
"yubikeys": ["ccccccccccce"],
"id": 43,
"name": "ford"
}
DELETE http://<host>/core/users/<id-or-username>
or
POST http://<host>/core/users/<id-or-username>/delete
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
Returns an empty response with status 204 No Content
on success.
POST http://<host>/core/users/<id-or-username>/reset
Parameters
password:
The users new password (required)
Example
curl http://127.0.0.1:8080/core/users/41/reset --data "password=newpass"
Returns an empty response with status 204 No Content
on success.
Checks if a given password and/or YubiKey OTP (One Time Password) is valid for the user.
GET or POST http://<host>/core/users/<id-or-username>/validate
Parameters
password
|
The value of the attribute to set |
otp
|
The value of the attribute to set |
Example
curl http://127.0.0.1:8080/core/users/41/validatepassword=foo&otp=ccccccccccceglgvbrbttbctichrejkvbjbgigetfgkr
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 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.
POST http://<host>/core/user/<id-or-username>/yubikeys
Parameters
yubikey
|
The prefix of the YubiKey to assign |
Example
curl http://127.0.0.1:8080/core/users/1/yubikeys --data "yubikey=ccccccccccce"
Returns an empty response with status 204 No Content
on success.
GET http://<host>/core/user/<id-or-username>/yubikeys/<prefix>
or
GET http://<host>/core/yubikeys/<prefix>
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
Returns a JSON representation of the YubiKey:
{
"attributes": {},
"prefix": "ccccccccccce",
"enabled": true,
"id": 53
}
DELETE http://<host>/core/user/<id-or-username>/yubikeys/<prefix>
or
POST http://<host>/core/user/<id-or-username>/yubikeys/<prefix>/delete
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
Returns an empty response with status 204 No Content
on success.
DELETE http://<host>/core/yubikeys/<prefix>
or
POST http://<host>/core/yubikeys/<prefix>/delete
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
Returns an empty response with status 204 No Content
on success.
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
.
GET http://<host>/core/<attribute_base>
Example
curl http://127.0.0.1:8080/core/users/42/attributes
A JSON object with key-values matching the attributes.
{
"full_name": "Ford Prefect"
"email": "ford@example.com",
}
Sets the value of an attribute. If the attribute already exists, it will be overwritten.
POST http://<host>/core/<attribute_base>
Parameters
key
|
The key of the attribute to set |
value
|
The value of the attribute to set |
Example
curl http://127.0.0.1:8080/core/users/42/attributes --data "key=email&value=ford@example.com"
Returns an empty response with status 204 No Content
on success.
Gets the value of a single attribute.
GET http://<host>/core/<attribute_base>/<key>
Example
curl http://127.0.0.1:8080/core/users/42/attributes/email
A JSON string, or null, for example:
"ford@example.com"
Removes an attribute, if it exists.
DELETE http://<host>/core/<attribute_base>/<key>
or
POST http://<host>/core/<attribute_base>/<key>/delete
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
Returns an empty response with status 204 No Content
.
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.
Validate user credentials. Also see Validating a users password and/or YubiKey under Users in the Core API.
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.
GET or POST http://<host>/client/authenticate
Parameters
username
|
The username of the user to authenticate |
password
|
The users password |
otp
|
A valid OTP from a YubiKey that is assigned to the user |
Example
curl http://127.0.0.1:8080/client/authenticate --data "username=trillian&password=foo"
Returns a JSON boolean true value if the given parameters are valid and sufficient to authenticate the given user, false otherwise.
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!"
}
Creates a new session for the given user, returning a session cookie.
GET or POST http://<host>/client/login
Parameters
username
|
The username of the user to authenticate |
password
|
The users password |
otp
|
A valid OTP from a YubiKey that is assigned to the user |
Example
curl http://127.0.0.1:8080/client/login --data "username=trillian&password=foo"
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.
GET or POST http://<host>/client/logout
Requires valid session
Example
curl http://127.0.0.1:8080/client/logout -H "X-YubiAuth-Session: 6cfb...be55"
Invalidates the session and returns a JSON boolean true value if the given session cookie was valid. Returns an error otherwise.
GET or POST http://<host>/client/status
Requires valid session
Example
curl http://127.0.0.1:8080/client/status -H "X-YubiAuth-Session: 6cfb...be55"
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
}
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).
GET or POST http://<host>/client/password
Requires valid session
Parameters
newpass
|
The new password to set for the user |
oldpass
|
The current password of the user |
otp
|
A valid OTP from a YubiKey that is assigned to the user |
Example
curl http://127.0.0.1:8080/client/password -d''
Returns a JSON boolean true value if successful.
Note
|
This API is not fully documented. |