Skip to content

Quick Start⚓︎

API Specification⚓︎

The entire server API specification is available through a web interface and as an OpenAPI YAML. You can use the Swagger web interface for manual testing of the API on the hosted authentication server. Do not forget to enter the API key first through the Authorize button.

Getting the SDK⚓︎

We recommend using an automatically generated library to integrate the nextAuth REST SDK into your application, instead of manually implementing the REST calls. See for instance Swagger Codegen or OpenAPI Generator.

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.

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.