REST API
Table of Contents
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.