REST API

Table of Contents

1. Getting the SDK
2. Functional Authentication in Three API Calls
   1. Initializing the SDK
   2. Generating a Session Identifier
   3. Checking the Current Session Status
   4. Display the Login Control
   5. Show a Register QR Code
3. Extending the Example

Getting the SDK

Before starting, install the appropriate nextAuth SDK to access the nextAuth API from your server environment.

Functional Authentication in Three API Calls

The example below shows how to achieve a functional login in three simple API calls. We use the PHP SDK in this example, but you can easily implement it in another language by using the same API calls. The full code can be downloaded from GitHub.

For simplicity, we assume the server has already been set up, either on a local NAS instance or using the nextAuth dashboard.

Initializing the SDK

The code below loads and initializes the SDK. Note that $apiKey needs to be set to the API key configured in the server. The $sessions variable will contain an object to access the session management calls of the API.

require_once(__DIR__ . '/vendor/autoload.php');

$config = new Nextauth\Configuration();
$config->setApiKey('x-apikey', $apiKey);
// When running a local nextAuth Authentication Server, make sure to set the host
//$config->setHost("http://localhost:8888/");

$client = new GuzzleHttp\Client();

$sessions = new Nextauth\Api\SessionsApi($client, $config);

Generating a Session Identifier

nextAuth needs a session identifier to refer to the browser session. In this case we use a SHA256 hash (hex-encoded) of the internal PHP session ID.

session_start();
$sessionid =  hash('sha256', session_id(), false);

Checking the Current Session Status

A call to getSession results in the login status of the current browser session. You can retrieve whether the user is logged in and, if so, under which user ID.

$loginStatus = $sessions->getSession($serverId, $sessionId);
var_dump($loginStatus);

if ($loginStatus->getLoggedIn()) {
    echo 'User ID: ' . htmlspecialchars($loginstatus->getUserId()) . '<br />';
}

Display the Login Control

Displaying the login button and/or QR code, is as simple as including the Login HTML from the getHtmlLogin API call:

echo $sessions->getHtmlLogin($serverId, $sessionId);

Make sure to include the footer near the end of your HTML page:

echo $sessions->getHtmlFooter($serverId, $sessionId);

Note that you can also create your own custom login controls. Restyling the CSS is the easiest way to do so.

For more control, you can use getQrLogin to retrieve a QR code (in PNG) or the raw data. Use getSession to determine if it is possible to perform a push login.

Show a Register QR Code

To allow a new device to be registered, a QR code needs to be shown using getHtmlEnrol. $displayName should contain the name of the user, as it is displayed in the app; $userId on the contrary is the userid used by the server.

echo $sessions->getHtmlEnrol($serverid, $sessionId, $displayName, $userId);

Extending the Example

You can easily extended the above example with more advanced functionality:

• perform a server-side logout;
• manage users and accounts with the Users and Accounts calls;
• start using user attributes with, e.g., getUserAttributes and corresponding setters;
• manually set the user ID for the currently active session through registerUser.