Skip to main content

Authentication

GET /auth/status​

Check whether the instance needs initial setup.

  • Auth required: No

Response

{ "needsSetup": true }

POST /auth/setup​

Create the initial admin account. Only available when needsSetup is true.

  • Auth required: No

Request body

{
  "username": "admin",
  "password": "strongpassword",
  "displayName": "Administrator"
}

Response

{
  "token": "<jwt>",
  "user": { "id": "...", "username": "admin", "role": "admin" }
}

GET /auth/providers​

Returns which authentication providers are enabled on this instance.

  • Auth required: No

Response

{
  "local": true,
  "ldap": false,
  "oidc": true,
  "oidcButtonLabel": "Sign in with Google"
}

POST /auth/login​

Authenticate with a local username and password.

  • Auth required: No
  • Rate limited: 30 attempts / 15 min per IP

Request body

{
  "username": "alice",
  "password": "hunter2"
}

Response — success

{
  "token": "<jwt>",
  "user": { "id": "...", "username": "alice", "role": "user" }
}

Response — MFA required

{
  "mfaRequired": true,
  "mfaToken": "<temporary-mfa-token>"
}

POST /auth/login/mfa​

Complete login when MFA is enabled.

  • Auth required: No (uses mfaToken from previous step)
  • Rate limited: 5 attempts / 5 min per user

Request body

{
  "mfaToken": "<temporary-mfa-token>",
  "code": "123456",
  "trustDevice": false
}

Response

{
  "token": "<jwt>",
  "user": { "id": "...", "username": "alice" }
}

POST /auth/login/ldap​

Authenticate via LDAP / Active Directory.

  • Auth required: No

Request body

{
  "username": "alice",
  "password": "hunter2"
}

Response

{
  "token": "<jwt>",
  "user": { "id": "...", "username": "alice" }
}

GET /auth/oidc/authorize​

Begin an OpenID Connect SSO flow. Redirects the browser to the identity provider.

  • Auth required: No

Response

{ "url": "https://accounts.google.com/o/oauth2/auth?..." }

GET /auth/oidc/callback​

OIDC provider callback endpoint. Handled automatically — redirects to /?sso=success on success or /?sso_error=<message> on failure.

  • Auth required: No

POST /auth/ldap/test​

Test LDAP connectivity. Requires admin auth.

  • Auth required: Yes
  • Permission: settings.manage

Request body

{
  "url": "ldap://dc.example.com:389",
  "bindDn": "cn=readonly,dc=example,dc=com",
  "bindPassword": "secret",
  "searchBase": "ou=users,dc=example,dc=com"
}

Response

{ "success": true }

POST /auth/logout​

Revoke the current session token.

  • Auth required: Yes

Response

{ "ok": true }

GET /auth/me​

Return the currently authenticated user.

  • Auth required: Yes

Response

{
  "user": {
    "id": "...",
    "username": "alice",
    "displayName": "Alice",
    "role": "user",
    "permissions": ["connections.create", "sessions.view_any"],
    "dismissedWarnings": []
  }
}

POST /auth/ws-ticket​

Issue a short-lived WebSocket ticket used to authenticate terminal/RDP connections.

  • Auth required: Yes

Response

{ "ticket": "<ws-ticket>" }