Documentation

rocket_launch Getting Started

AuthSys provides a full identity and access management API. Browser requests use the Secure, HttpOnly AuthSys session cookie. OAuth/API resource requests use a valid bearer token over HTTPS.

info

All API responses are JSON. Include Content-Type: application/json in your request headers.

checklist

Quick Start

3 Steps

Register an account at /api/auth/register
Login at /api/auth/login to establish the HttpOnly browser session
Exchange an authorization code from a registered application at /api/oauth/token
Send Authorization: Bearer <token> only to protected OAuth/API resources

lock Authentication

AuthSys uses an HttpOnly browser session for first-party web pages and OAuth/OIDC bearer tokens for registered client applications.

Method	Endpoint	Description
POST	`/api/auth/register`	Create a new account
POST	`/api/auth/login`	Login and establish a Secure, HttpOnly browser session
POST	`/api/auth/logout`	End the current browser session (or revoke a compatibility bearer session)
POST	`/api/auth/refresh-token`	Exchange refresh token for new JWT
GET	`/api/auth/profile`	Get authenticated user profile

schedule

Browser session: 1 hour by default or 30 days with "Remember me" · OAuth access token: 1 hour (RS256) · OIDC ID token: 1 hour (RS256) · Refresh token: issued only with registered offline_access

key OAuth Applications

Register applications that use AuthSys for user sign-in. The Client ID and Client Secret identify an OAuth client; they are not general-purpose API keys and do not grant access on their own. Users authenticate with AuthSys, and the application exchanges a one-time authorization code with its PKCE verifier for tokens. Manage applications from the Applications dashboard.

Method	Endpoint	Description
GET	`/api/oauth/clients`	List your OAuth client applications
POST	`/api/oauth/clients`	Register a new client (returns client_id + client_secret once)
GET	`/api/oauth/clients/:id`	Get client details
PUT	`/api/oauth/clients/:id`	Update client settings
DELETE	`/api/oauth/clients/:id`	Deactivate a client

warning

The client secret is shown only once at creation. Store it securely — it cannot be retrieved again.

device_hub OAuth 2.0 Flow

AuthSys supports OAuth 2.0 Authorization Code flow with PKCE for third-party app integration.

Method	Endpoint	Description
GET	`/api/oauth/authorize`	Start authorization — redirect user here
POST	`/api/oauth/token`	Exchange authorization code for tokens
GET	`/api/oauth/userinfo`	Get user info with access token
POST	`/api/oauth/revoke`	Revoke an access or refresh token
POST	`/api/oauth/introspect`	Inspect a token's validity and claims

login

Social Login

Passport.js

Google: GET /api/auth/google
GitHub: GET /api/auth/github

api Endpoints Reference

Method	Endpoint	Auth Required	Description
POST	`/api/auth/forgot-password`	No	Request password reset email
POST	`/api/auth/reset-password/:token`	No	Reset password with token
GET	`/api/auth/sessions`	Yes	List active sessions
DELETE	`/api/sessions/:sessionId`	Yes	Revoke a specific session
GET	`/health`	No	Server health check

error Error Codes

Status	Code	Description
200	OK	Request succeeded
400	Bad Request	Invalid parameters or missing fields
401	Unauthorized	Missing or invalid token
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
423	Locked	Account locked due to too many failed attempts
429	Too Many Requests	Rate limit exceeded
500	Server Error	Unexpected server-side error

speed Rate Limiting

Rate limits are applied per IP address on sensitive endpoints.

Endpoint Group	Limit	Window
Login / Register	10 requests	15 minutes
Password Reset	5 requests	1 hour
OAuth Token	20 requests	15 minutes
General API	100 requests	15 minutes