menu_book

Documentation

AuthSys API Reference & Integration Guide

arrow_back Back
API v1.0 Base URL: http://localhost:5000/api
OAuth 2.0

format_list_numbered Table of Contents

  1. Getting Started
  2. Authentication
  3. API Keys
  4. OAuth 2.0 Flow
  5. Endpoints Reference
  6. Error Codes
  7. Rate Limiting
  8. Security

rocket_launch Getting Started

AuthSys provides a full identity and access management API. All requests must be made over HTTPS and include a valid authentication token.

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 to receive a JWT token at /api/auth/login
  • Pass the token as Authorization: Bearer <token> on every request

lock Authentication

AuthSys uses JWT (JSON Web Tokens) for authentication.

Method Endpoint Description
POST /api/auth/register Create a new account
POST /api/auth/login Login and receive JWT + refresh token
POST /api/auth/logout Invalidate current token
POST /api/auth/refresh-token Exchange refresh token for new JWT
GET /api/auth/profile Get authenticated user profile
schedule
Access token: 1 hour (HS256) · Refresh token: 30 days (rotated on use)
"Remember me" changes token storage (localStorage), not expiry time

key API Keys

API keys allow programmatic access to the AuthSys API without interactive login. Manage your keys from the API Keys 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
API keys are shown only once at creation. Store them securely — they 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/token/revoke Revoke an access or refresh token
POST /api/oauth/token/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/auth/sessions/:id 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
info
When rate limited, the response will include a Retry-After header indicating when to retry.

security Security

AuthSys implements the following security measures:

API v1.0 Last updated: March 2026

This documentation covers the current stable API.
Breaking changes will be versioned.

arrow_back Go Back Get Started