API Specification: Authentication

Service Owner

apps/manager (Identity Provider)

Base URL

/api/v1/auth

1. Registration & Login

POST /register

Create a new user account.

• Body:

  {
    "email": "jane@company.com",
    "password": "securePassword123",
    "name": "Jane Doe"
  }

• Response (201 Created):

  {
    "data": {
      "user": { "id": "u_123", "email": "jane@company.com" },
      "token": "ey..." // Short-lived Access Token
    }
  }

POST /login

Authenticate with credentials.

• Body:

  {
    "email": "jane@company.com",
    "password": "securePassword123"
  }

• Response (200 OK):

  {
      "access_token": "ey...",
      "user": { ... },
      "tenant": { ... }
  }

• Note: NextAuth converts this into an httpOnly session cookie on the frontend; Manager remains stateless.

2. Session Management

POST /refresh

Exchange a soon-to-expire JWT for a newly signed JWT.

• Auth: Requires the old access_token in Authorization: Bearer <token>
• Body:

  {
    "refresh_token": "ey_old_access_token..."
  }

• Response (200 OK):

  {
     "access_token": "ey_new_access_token..." 
  }

POST /logout

Invalidate session.

• Action: Clears cookies, blacklists JTI (optional).
• Response (200 OK): { "data": { "success": true } }

3. Password Management

POST /forgot-password

Initiate reset flow.

• Body: { "email": "..." }
• Response: 200 OK (Always, to prevent enumeration).

POST /reset-password

Complete reset.

• Body:

  {
    "token": "reset_token_xyz",
    "new_password": "newPassword123"
  }

4. Federated Identity (OAuth)

GET /oauth/:provider

Redirect to provider (Google/GitHub).

• Query: ?redirect_to=/dashboard

GET /oauth/:provider/callback

Handle return from provider.

• Action: Creates/Links user, sets cookies.

5. Error Codes