AUTHN API Reference
Module Information
Service Files:
- Private:
service/authn.js - Public:
service/authn.js
Available Services: 5 Documented Services: 5
authn.create
Exchange an HTTP Authorization header credential for a short-lived opaque token. The credential is stored via the authn_store procedure and the generated token is returned to the caller for subsequent authenticated requests.
| Property | Value |
|---|---|
| Scope | Hub (requires hub context) |
| Permission | Anyone (1) |
Endpoint:
https://hostname/-/api/authn.create
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
Authorization | string | Yes | - | Standard HTTP Authorization header (e.g. Basic or Bearer scheme). Read from the request header, not the request body. |
Returns
| Field | Type | Description |
|---|---|---|
token | string | 22-character opaque authentication token generated by uniqueId(22) and persisted via the authn_store stored procedure |
Possible Errors
| Error Code | HTTP Status | Description |
|---|---|---|
UNAUTHORIZED | 401 | Authorization header is missing or malformed |
INTERNAL_ERROR | 500 | Failed to persist token via authn_store procedure |
authn.begin
Begin a CLI device-pairing (npm-style login). Creates a pending pairing and returns a device_code the CLI polls with and a short user_code the user approves in the app. Anonymous.
| Property | Value |
|---|---|
| Scope | Hub (requires hub context) |
| Permission | Anonymous (1) |
Endpoint:
https://hostname/-/api/authn.begin
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
label | string | No | - | Human label for the device/session being paired |
Returns
| Field | Type | Description |
|---|---|---|
device_code | string | Secret handle the CLI polls with |
user_code | string | Short code the user approves in the app |
expires | integer | Unix timestamp when the pairing expires |
interval_seconds | integer | Suggested poll interval in seconds |
authn.poll
Poll a pending CLI pairing by device_code. Returns the minted token once the user has approved it in the app (one-time delivery), otherwise the current status. Anonymous.
| Property | Value |
|---|---|
| Scope | Hub (requires hub context) |
| Permission | Anonymous (1) |
Endpoint:
https://hostname/-/api/authn.poll
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
device_code | string | Yes | - | The device_code returned by authn.begin |
Returns
| Field | Type | Description |
|---|---|---|
status | string | pending, approved, expired or unknown |
token | string | The minted CLI token, present only when status is approved |
authn.approve
Approve a pending CLI pairing for the currently signed-in user. Called from the app Authorize action. Requires owner privilege. The identity is taken from the session, not the request body. Mints a CLI token bound to this user and attaches it to the pairing.
| Property | Value |
|---|---|
| Scope | Hub (requires hub context) |
| Permission | Owner (32) |
Endpoint:
https://hostname/-/svc/authn.approve
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
user_code | string | Yes | - | The user_code shown by the CLI |
label | string | No | - | Human label for the device/session |
ttl_days | integer | No | - | Token lifetime in days; 0 means no expiry; defaults to 90 |
Returns
| Field | Type | Description |
|---|---|---|
failed | integer | 0 on success, 1 on failure |
reason | string | Failure reason when failed is 1 |
authn.create_pat
Mint a Personal Access Token for headless or CI use, bound to the currently signed-in user. Called from account settings. Requires owner privilege. Returns the token once.
| Property | Value |
|---|---|
| Scope | Hub (requires hub context) |
| Permission | Owner (32) |
Endpoint:
https://hostname/-/svc/authn.create_pat
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
label | string | No | - | Human label for the token |
ttl_days | integer | No | - | Token lifetime in days; 0 means no expiry; defaults to 0 |
Returns
| Field | Type | Description |
|---|---|---|
token | string | The Personal Access Token, shown once |
exp | integer | Unix expiry timestamp, 0 when no expiry |
label | string | The token label |
Related Documentation
- ACL System - Permission model
- ACL Specification - Scope, permission and routing reference
- Request Pipeline - How requests are routed
- Error Handling - Error codes