The HTTP methods that are LRS-specific are given in the xAPI spec. Requests to the LRS (which are denoted by the xapi
path prefix) must contain a Base64 encoded, colon-separated public and secret API key pair in the Authorization
field of the header. For example (assuming http://example
is the URL body), http://example.org/xapi/statements
is the URL at which the user inserts and queries xAPI statements; other URLs are used to insert and query documents, agents, and activities.
In addition to the LRS HTTP methods, the SQL LRS supports methods for admin account creation, login, and use, as well as routes used to create and use API ; these methods are denoted by the admin
path prefix.
The following examples use http://example.org
as the URL body. All methods return 200 OK
on success. All routes except for account/login
and admin/env
must contain a JSON Web Token (JWT), generated by account creation or login, in the Authorization
header in the form of Bearer [JWT]
; if the JWT is expired or invalid a 401 UNAUTHORIZED
is returned. All methods also require that the request body be a JSON object, though the permitted values depend on the route; invalid request bodies will result a 400 BAD REQUEST
error. If an error is encountered, these routes return a JSON object in the body like the following:
{
"error": "[error message]"
}
POST http://example.org/admin/account/login
: Log into an existing account. The request body must be a JSON object that contains username
and password
strings. These must conform to the following requirements:username
must be a minimum of 7 characters.password
must be a minimum of 10 characters.password
must contain at least one lower case character.password
must contain at least one upper case character.password
must contain at least one numeric character.password
must contain at least one of the following special characters: !@#$%^&*_-+=?
.The response body contains a newly generated JSON Web Token (JWT) on success. A 401 UNAUTHORIZED
status code is returned if the credentials are incorrect.
POST http://example.org/admin/account/logout
: Log out of the current account. This will revoke any unexpired JWTs associated with the user. (NOTE: This endpoint will return a 400 BAD REQUEST
error if LRSQL_JWT_NO_VAL
is set to true
.)GET http://example.org/admin/account/renew
: Renew the current account's login session by issuing a new JWT. For a given JWT, the renewal is only granted if the current time is less than the ref
timestamp (which is determined by LRSQL_JWT_REFRESH_EXP_TIME
).POST http://example.org/admin/account/create
: Create a new admin account. The request body must be a JSON object that contains username
and password
strings. The endpoint returns a JSON object with the ID (UUID) of the newly created user on success, and returns a 409 CONFLICT
if the account already exists.DELETE http://example.org/admin/account
: Delete an existing account. The JSON request body must contain a UUID account-id
value. The endpoint returns a JSON object with the ID of the deleted account on success and returns a 404 NOT FOUND
error if the account does not exist.GET http://example.org/admin/account
: Return an array of all admin accounts in the system on success.GET http://example.org/admin/me
: Returns the currently authenticated admin accounts on success.GET http://example.org/admin/verify
: Returns a 204 No Content
response, without a body, on success (the success conditions are the same as the /admin/me
endpoint).POST http://example.org/admin/creds
: Create a new credential pair, with the specified scope values given by the scopes
property in the request body.PUT http://example.org/admin/creds
: Update an existing credential pair, given by api-key
and secret-key
properties in the request body, with the new scopes given by the scopes
property.GET http://example.org/admin/creds
: Read all credential pairs and their associated scopes for a particular account (denoted by the JWT).DELETE http://example.org/admin/creds
: Delete an existing credential pair, given by the api-key
and secret-key
properties in the request body, as well as any associated scopes.GET http://example.org/admin/csv/auth
: Return a one-time JWT for use for /admin/csv
, used in order to use the latter endpoint as a download
attribute for HTML anchor tags and authenticate without headers.GET http://example.org/admin/csv
: Download statements in the LRS as a CSV filestream. This endpoint accepts the statement query parameters defined in the xAPI spec, but allows two additional parameters: the one-time JWT token
string and the URL-encoded property-path
vector strings.GET http://example.org/admin/env
: Get select environment variables about the configuration which may aid in client-side operations.GET http://example.org/admin/openapi
: Get an OpenAPI JSON spec of the endpoint API, which can then be visualized using an OpenAPI viewer like Swagger.GET http://example.org/admin/status
: Get LRS status information, such as the number of statements in the LRS.DELETE http://example.org/admin/agents
: Runs a hard delete of all records of an actor, and associated records (statements, attachments, etc). Intended for privacy purposes like GDPR. Body should be a JSON object of form {"actor-ifi":<actor-ifi>}
. Disabled unless the configuration variable enableAdminDeleteActor to be set to true
.If Reactions are enabled, the following routes can be used to manage them:
POST http://example.org/admin/reaction
: Create a new reaction by providing a JSON ruleset
and active
boolean. On success returns 200 with the reactionId
of the new reaction.GET http://example.org/admin/reaction
: List all reactions, active and inactive.PUT http://example.org/admin/reaction
: Given a reactionId
and either a JSON ruleset
or boolean active
parameter, update the given reaction. On success returns 200 with the reactionId
of the updated reaction. Returns 404 if the reaction is not found.DELETE http://example.org/admin/reaction
: Delete a reaction specified by reactionId
. Returns 200 with the reactionId
of the deleted reaction on success or 404 if not found.