Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/gnmyt/Nexterm/llms.txt

Use this file to discover all available pages before exploring further.

The authentication endpoints let you create and destroy sessions, verify identities using WebAuthn passkeys, and authorize headless devices such as mobile apps or CLI connectors through a device-code flow. Every other API endpoint requires the Bearer token returned by a successful login.

​
POST /api/auth/login

Authenticates a user with a username and password. If the account has TOTP (two-factor authentication) enabled, the current six-digit code must be included as code. Returns the session token in both the Authorization response header and the JSON body.

​
Request body

​
username
string
required
Account username. Maximum 255 characters.
​
password
string
required
Account password. Maximum 255 characters.
​
code
number
Six-digit TOTP code. Required when the account has two-factor authentication enabled.

​
Response

​
token
string
96-character hex session token. Also set in the Authorization response header.
​
message
string
Confirmation message.
curl --request POST \
  --url http://your-server:6989/api/auth/login \
  --header 'Content-Type: application/json' \
  --data '{"username": "admin", "password": "s3cr3t"}'

​
POST /api/auth/logout

Invalidates a session token, logging out the associated user.

​
Request body

​
token
string
required
The 96-character hex session token to invalidate.

​
Response

​
message
string
Confirmation that the session was deleted.
curl --request POST \
  --url http://your-server:6989/api/auth/logout \
  --header 'Content-Type: application/json' \
  --data '{"token": "a1b2c3d4..."}'

​
POST /api/auth/passkey/options

Retrieves WebAuthn authentication options needed to initiate a passkey login. Call this before POST /api/auth/passkey/verify.

​
Request body

​
username
string
required
The username of the account to authenticate.
​
origin
string
required
The origin of the requesting application (e.g. https://nexterm.example.com).

​
Response

Returns a WebAuthn PublicKeyCredentialRequestOptions object to pass to navigator.credentials.get(). 
curl --request POST \
  --url http://your-server:6989/api/auth/passkey/options \
  --header 'Content-Type: application/json' \
  --data '{"username": "admin", "origin": "https://nexterm.example.com"}'

​
POST /api/auth/passkey/verify

Verifies a passkey authentication response produced by the browser’s WebAuthn API and creates a new session on success.

​
Request body

​
response
object
required
The AuthenticationResponseJSON object returned by navigator.credentials.get().
​
origin
string
required
The origin of the requesting application.

​
Response

​
token
string
Session token. Also set in the Authorization response header.
​
message
string
Confirmation message.
curl --request POST \
  --url http://your-server:6989/api/auth/passkey/verify \
  --header 'Content-Type: application/json' \
  --data '{"response": {...}, "origin": "https://nexterm.example.com"}'

​
POST /api/auth/device/create

Creates a short-lived device authorization code for use in the mobile app or connector authentication flow. The code is displayed (or encoded as a QR) for the user to approve from the web interface. Rate-limited to 10 requests per hour per IP for unauthenticated callers.

​
Request body

​
clientType
string
required
Type of client requesting authorization. Valid values: mobile, connector.

​
Response

​
code
string
Short alphanumeric code the user enters in the web interface.
​
token
string
Polling token used with POST /api/auth/device/poll.
curl --request POST \
  --url http://your-server:6989/api/auth/device/create \
  --header 'Content-Type: application/json' \
  --data '{"clientType": "mobile"}'

​
POST /api/auth/device/poll

Polls for the authorization status of a pending device code. Call this repeatedly until the status changes from pending.

​
Request body

​
token
string
required
The polling token returned by POST /api/auth/device/create.

​
Response

​
status
string
Current authorization status. One of pending, authorized, or invalid.
​
token
string
Session token. Only present when status is authorized.
curl --request POST \
  --url http://your-server:6989/api/auth/device/poll \
  --header 'Content-Type: application/json' \
  --data '{"token": "poll-token-here"}'

​
POST /api/auth/device/info

Retrieves information about a pending device code so the user can review device details before approving. Requires authentication.

​
Request body

​
code
string
required
The device authorization code to look up.

​
Response

​
clientType
string
The type of client that created the code (mobile or connector).
​
ipAddress
string
IP address the device code request originated from.
​
userAgent
string
User-agent string of the device.
curl --request POST \
  --url http://your-server:6989/api/auth/device/info \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"code": "ABC123"}'

​
POST /api/auth/device/authorize

Approves a pending device code, linking it to the authenticated user’s account. Once authorized, the device can retrieve a session token by polling. Requires authentication.

​
Request body

​
code
string
required
The device authorization code to approve.

​
Response

​
message
string
Confirmation that the code was authorized.
curl --request POST \
  --url http://your-server:6989/api/auth/device/authorize \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"code": "ABC123"}'

​
POST /api/auth/device/link/status

Checks whether a device code created for QR-based linking has been claimed (polled and session retrieved) by the mobile app. Requires authentication.

​
Request body

​
code
string
required
The device authorization code to check.

​
Response

​
status
string
One of pending, authorized, claimed, or expired.
curl --request POST \
  --url http://your-server:6989/api/auth/device/link/status \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"code": "ABC123"}'

​
GET /api/session/list

Returns all active sessions for the authenticated user, excluding the session used for the request itself. Useful for auditing connected devices. Requires authentication.

​
Response

Returns an array of session objects.
​
[].id
number
Session identifier.
​
[].ip
string
IP address that created the session.
​
[].userAgent
string
User-agent string of the client.
​
[].lastActivity
string
ISO 8601 timestamp of the last request made with this session.
curl --request GET \
  --url http://your-server:6989/api/session/list \
  --header 'Authorization: Bearer YOUR_TOKEN'

​
DELETE /api/session/:id

Destroys a specific session by its ID, logging out that session across all devices. Requires authentication.

​
Path parameters

​
id
string
required
The unique identifier of the session to destroy.

​
Response

Returns the result of the destroy operation. 
curl --request DELETE \
  --url http://your-server:6989/api/session/7 \
  --header 'Authorization: Bearer YOUR_TOKEN'

Build docs developers (and LLMs) love

Get started for freeTalk to us