WESB ID Integration Guide

1. Purpose

WESB ID is the central identity platform for Weststar internal applications.

In the current product, WESB ID is no longer only a user-lookup service. It is now the hosted login authority for connected internal applications.

That means:

• the connected site does not store the user's WESB ID password
• the user signs in on WESB ID itself
• WESB ID returns a short-lived one-time auth code to the connected site
• the connected site exchanges that auth code server-to-server using its site-owned X-Service-Key
• the connected site can then auto-provision or update its own local linked user by wesb_user_id

This guide is written for a developer who does not have access to the WESB ID admin panel. You can read this guide publicly, but you cannot complete the integration alone. A WESB ID administrator must register your site, configure its policy, approve its callback URLs, and generate its service key before integration is valid.

2. Current Integration Model

The primary integration model is now:

1. site registration by WESB ID Super Admin
2. callback URL approval
3. service-key generation
4. browser redirect to hosted WESB ID login
5. successful callback with one-time auth code
6. backend auth-code exchange using X-Service-Key
7. local linked-user auto-provision by wesb_user_id

The older resolve and token endpoints still exist, but they are no longer the main login delegation path.

3. Important Terminology

3.1 Site Registration

Site Registration is the admin-managed process of creating your application inside the WESB ID Site Registry.

A registered site stores metadata such as:

• site_key
• site_name
• base_url
• support_label
• logo_url
• brand_color
• status
• service_key_prefix
• service_key_last_used_at

Operational meaning:

• the site record is the governance record for your application
• the approved site_key is the canonical application identifier
• the site must be active before hosted login or backend exchange will work

3.2 Site Policy

Site Policy is the per-site authentication contract managed by WESB ID admin.

In the current product, the policy surface includes:

• auth_mode
  • hosted_login
• login_mode
  • password_only
  • otp_required
• reset_mode
  • reset_link
  • otp_email
• allow_password_reset
• enforce_2fa
• allowed_origins_json
• callback_urls_json

Operational meaning:

• auth_mode = hosted_login means the connected site must redirect users to WESB ID instead of verifying passwords locally
• callback_urls_json is part of the trust boundary
• login_mode and enforce_2fa control whether hosted login finishes after password entry or requires email OTP

3.3 Service Key

Each approved site can own one active service key at a time.

Current behavior:

• generated by WESB ID Super Admin from the Sites screen
• shown once immediately after generation or rotation
• stored only as a hash plus visible prefix
• rotation invalidates the previous key immediately
• used only for trusted backend calls, never in frontend code

3.4 Hosted Login Auth Code

After a successful hosted WESB ID login, WESB ID creates a short-lived one-time authorization code.

Current behavior:

• bound to one site
• bound to one approved callback URL
• short-lived
• single-use
• exchanged server-to-server

3.5 Auxiliary Service APIs

WESB ID still exposes:

• GET /api/service/resolve
• POST /api/service/token

These can still be used for auxiliary identity lookups or internal trusted flows, but they are not the primary delegated-login handoff anymore.

4. What You Can and Cannot Do Without Admin Access

You can do

• prepare your application metadata
• prepare callback URLs and origin lists
• implement the redirect and backend exchange flow in your application
• test request formatting and response handling
• use this document to align with the current WESB ID contract

You cannot do

• register your own site
• approve your own callback URLs
• generate your own authoritative service key
• rotate a site service key
• bypass WESB ID hosted login and still claim the integration is complete

5. Information You Must Send to WESB ID Admin

Before development sign-off, send the following to the WESB ID admin team:

1. Site name
2. Proposed site_key
3. Base URL
4. Support label
5. Allowed frontend origins
6. Callback URLs
7. Desired hosted login mode
8. Desired reset mode
9. Whether password reset must be allowed
10. Whether 2FA must be enforced

Recommended request template:

Site name: ATP Console
Site key: atp
Base URL: https://atp.weststar-dev.com
Support label: ATP Support
Allowed frontend origins:
- https://atp.weststar-dev.com
- https://staging-atp.weststar-dev.com
Callback URLs:
- https://atp.weststar-dev.com/auth/callback
- https://staging-atp.weststar-dev.com/auth/callback
Desired auth mode: hosted_login
Desired login mode: otp_required
Desired reset mode: reset_link
Allow password reset: yes
Enforce 2FA: yes

6. What You Should Expect Back From WESB ID Admin

The WESB ID admin team should provide:

1. confirmation that the site was registered
2. the approved site_key
3. the final site policy values
4. the approved callback URL(s)
5. the site-owned service key or the approved secure handoff process for it
6. the WESB ID base URL for the environment you are integrating with

Minimum outcome before implementation sign-off:

• your team knows the exact hosted-login URL to redirect to
• your team knows the exact callback URL that WESB ID will accept
• your backend has received the site-owned service key securely

7. Step-by-Step Hosted Login Integration

Step 1. Prepare application metadata

Developer action:

• collect the registration data listed above
• decide the exact callback URL(s) your backend will accept

Expected result:

• you have a complete site-registration request for WESB ID admin

Step 2. Contact WESB ID admin

Developer action:

• send the registration package
• explicitly state that your application will use hosted WESB ID login

Expected result:

• WESB ID admin reviews the site metadata, callback URLs, and login policy

Step 3. WESB ID admin registers the site

Admin-side action:

• create the site record in the Site Registry

Expected result:

• your application exists in WESB ID as a registered site

Step 4. WESB ID admin configures Site Policy

Admin-side action:

• set auth_mode = hosted_login
• configure login mode, reset mode, password reset allowance, 2FA enforcement, allowed origins, and callback URLs

Expected result:

• your application has an explicit hosted-login policy contract

Step 5. WESB ID admin generates the site service key

Admin-side action:

• generate the site service key from the Sites modal
• copy the one-time revealed plaintext key

Expected result:

• the site now has one active backend integration key

Step 6. Store WESB ID settings in your application

Developer action:

• store the WESB ID base URL
• store the approved site_key
• store the site-owned service key in backend-only environment configuration

Recommended environment variables in the connected application:

WESB_ID_BASE_URL=https://id.weststar-dev.com
WESB_ID_SITE_KEY=atp
WESB_ID_LOGIN_URL=https://id.weststar-dev.com/connect/login
WESB_ID_CALLBACK_URL=https://atp.weststar-dev.com/auth/callback
WESB_ID_SERVICE_KEY=replace-with-approved-site-service-key

Expected result:

• your application can redirect users to WESB ID and perform authenticated backend exchange

Step 7. Redirect users to hosted WESB ID login

Developer action:

• when a user clicks your app's login entry point, redirect them to:

GET https://id.weststar-dev.com/connect/login?site_key=YOUR_SITE_KEY&redirect_uri=YOUR_CALLBACK_URL&state=YOUR_STATE

Expected result:

• WESB ID renders a hosted login page for your registered site
• if the callback URL is not approved, WESB ID rejects the request

Step 8. Handle the callback

After successful WESB ID login:

• WESB ID redirects the browser back to your callback URL
• the callback query includes:
  • code
  • optional state

Example:

https://atp.weststar-dev.com/auth/callback?code=ONE_TIME_CODE&state=abc123

Expected result:

• your backend receives a one-time authorization code

Step 9. Exchange the auth code server-to-server

Developer action:

• your backend calls WESB ID with the site-owned service key
• do not perform this exchange from frontend JavaScript

Example:

curl -X POST "https://id.weststar-dev.com/api/service/exchange" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Service-Key: YOUR_SITE_SERVICE_KEY" \
  -d "{\"code\":\"ONE_TIME_CODE\"}"

Expected success response:

{
  "data": {
    "wesb_user_id": 123,
    "email": "staff.user@weststar.com",
    "full_name": "Staff User",
    "first_name": "Staff",
    "last_name": "User",
    "status": "active",
    "role": "staff",
    "department": "Technology",
    "job_title": "Developer",
    "profile_photo_url": null
  }
}

Expected result:

• your backend now has trusted identity data from WESB ID
• your app can auto-provision or update its own linked local user by wesb_user_id
• your app can then start its own local session

Step 10. Auto-provision the local app user

Developer action:

• find a local user by wesb_user_id
• if not found, create one
• if found, update profile fields as needed

Recommended minimum local linkage:

• wesb_user_id
• email
• full_name
• your app-specific role / team / ownership fields

Do not copy:

• the WESB ID password
• the WESB ID password hash

Expected result:

• users can log into the new site without separate site registration
• WESB ID remains the single password authority

8. Auxiliary Backend APIs

8.1 Resolve WESB user

Purpose:

• look up a WESB ID user by email or WESB user id

Example:

curl -X GET "https://id.weststar-dev.com/api/service/resolve?email=staff.user@weststar.com" \
  -H "Accept: application/json" \
  -H "X-Service-Key: YOUR_SITE_SERVICE_KEY"

8.2 Auxiliary lightweight token

Purpose:

• request an auxiliary lightweight token payload for trusted internal workflows

This is no longer the main delegated-login callback contract.

Example:

curl -X POST "https://id.weststar-dev.com/api/service/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Service-Key: YOUR_SITE_SERVICE_KEY" \
  -d "{\"wesb_user_id\":123}"

9. Required Negative Tests

9.1 Missing service key

Request:

curl -X POST "https://id.weststar-dev.com/api/service/exchange" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{\"code\":\"ONE_TIME_CODE\"}"

Expected result:

{
  "message": "Invalid service key."
}

9.2 Invalid service key

Request:

curl -X POST "https://id.weststar-dev.com/api/service/exchange" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Service-Key: WRONG_VALUE" \
  -d "{\"code\":\"ONE_TIME_CODE\"}"

Expected result:

• 401 Invalid service key.

9.3 Invalid callback URL

Operational test:

• try to open hosted login with a callback URL that is not listed in the site's approved callback URLs

Expected result:

• WESB ID rejects the request

9.4 Reused auth code

Operational test:

• exchange the same code twice

Expected result:

• first exchange succeeds
• second exchange fails

9.5 Cross-site exchange attempt

Operational test:

• obtain a valid auth code for site A
• try to exchange it with site B's X-Service-Key

Expected result:

• WESB ID rejects the exchange

10. Expected Results Summary

When integration is configured correctly:

1. the site is registered and active in WESB ID
2. hosted-login callback URLs are approved
3. the site has one active service key
4. the connected site redirects users to WESB ID for login
5. WESB ID returns a one-time auth code to the approved callback URL
6. the connected backend exchanges that code successfully using X-Service-Key
7. the connected site auto-provisions or updates its local linked user by wesb_user_id
8. the connected site never stores the user's WESB ID password

11. Integration Complete Checklist

• Site registration request sent to WESB ID admin
• Site registration approved
• Approved site_key received
• Approved callback URL(s) received
• Hosted login policy confirmed
• WESB ID base URL stored in your environment
• Site-owned service key stored securely in backend environment
• /connect/login?site_key=...&redirect_uri=... tested successfully
• Callback with code observed successfully
• POST /api/service/exchange tested successfully
• Missing-key request verified to fail with 401
• Invalid-key request verified to fail with 401
• Reused-code request verified to fail
• Local linked-user auto-provision confirmed
• No WESB ID password stored locally

12. Final Technical Notes

• WESB ID is an internal Weststar identity provider, not a public self-service platform
• do not expose the site service key in frontend code, committed source, or public logs
• do not bypass hosted login by asking the connected site to verify WESB ID passwords locally
• if your integration needs more fields at exchange time, raise the requirement with WESB ID admin instead of inventing a private unsupported contract

API Endpoint Catalog

This section is the source for the API Endpoints tab on the public integration-guide page.

Important scope note:

• not every endpoint below is intended for outside developers
• admin and staff session APIs are listed for completeness
• the primary non-admin integration surface is the hosted browser login plus the /api/service/* family

A. Public Hosted Login Endpoints

A.1 Hosted Login Start

Method	Path	Auth	Purpose
GET	/connect/login	Public	Render the hosted WESB ID login page for a registered site and approved callback URL
POST	/connect/login	Public	Verify WESB ID email/password and either issue OTP challenge or redirect with auth code
POST	/connect/login/verify	Public	Verify hosted login OTP and redirect with auth code

A.2 Hosted Login Query / Form Inputs

Required context values:

• site_key
• redirect_uri

Optional:

• state

B. Admin Session APIs

B.1 Admin Auth

Method	Path	Auth	Purpose
POST	/api/admin/auth/login	Public web session entry	Start an admin or super admin session
POST	/api/admin/auth/logout	admin.auth	End the current admin session
GET	/api/admin/auth/me	admin.auth	Return the current authenticated admin identity
POST	/api/admin/auth/change-password	admin.auth	Change the current admin password

B.2 Admin User Management

Method	Path	Auth	Purpose
GET	/api/admin/users	admin.auth	List visible users for the signed-in managing role
GET	/api/admin/users/{type}/{id}	admin.auth	Show one user record
POST	/api/admin/users	admin.auth	Create a staff or admin user, subject to role restrictions
PUT	/api/admin/users/{type}/{id}	admin.auth	Update a user record
PATCH	/api/admin/users/{type}/{id}/status	admin.auth	Change a user's status
PATCH	/api/admin/users/{type}/{id}/role	admin.auth + super_admin	Change a user's role
DELETE	/api/admin/users/{type}/{id}	admin.auth + super_admin	Delete a user record

B.3 Admin Job Titles

Method	Path	Auth	Purpose
GET	/api/admin/job-titles	admin.auth + super_admin	List job titles
POST	/api/admin/job-titles	admin.auth + super_admin	Create a job title
PUT	/api/admin/job-titles/{jobTitle}	admin.auth + super_admin	Update a job title
PATCH	/api/admin/job-titles/{jobTitle}/deactivate	admin.auth + super_admin	Deactivate a job title

B.4 Admin Sites

Method	Path	Auth	Purpose
GET	/api/admin/sites	admin.auth + super_admin	List registered sites
POST	/api/admin/sites	admin.auth + super_admin	Register a new site and generate its first service key
PUT	/api/admin/sites/{site}	admin.auth + super_admin	Update site metadata
POST	/api/admin/sites/{site}/service-key	admin.auth + super_admin	Rotate the site's service key
DELETE	/api/admin/sites/{site}	admin.auth + super_admin	Delete a registered site

B.5 Admin Policy

Method	Path	Auth	Purpose
POST	/api/admin/policy	admin.auth + super_admin	Create or update a site's hosted-login policy

B.6 Admin Audit

Method	Path	Auth	Purpose
GET	/api/admin/audit	admin.auth	List audit-log entries

C. Staff Session APIs

C.1 Staff Auth

Method	Path	Auth	Purpose
POST	/api/staff/auth/login	Public web session entry	Start a staff session for the WESB ID app itself
POST	/api/staff/auth/logout	auth:staff	End the current staff session
GET	/api/staff/auth/me	auth:staff	Return the current authenticated staff identity

C.2 Staff Password Reset

Method	Path	Auth	Purpose
POST	/api/staff/password/request	Public	Start password reset for a site-aware staff flow
POST	/api/staff/password/validate	Public	Validate a link-based password-reset token
POST	/api/staff/password/complete	Public	Complete password reset by token or OTP path

C.3 Staff Onboarding

Method	Path	Auth	Purpose
POST	/api/staff/onboarding/request	Public	Request first-time activation OTP
POST	/api/staff/onboarding/verify	Public	Verify the onboarding OTP
POST	/api/staff/onboarding/set-password	Public	Set the first password after onboarding verification

C.4 Staff Second Factor

Method	Path	Auth	Purpose
POST	/api/staff/factor/challenge	auth:staff + site.policy	Issue a staff OTP factor challenge when required
POST	/api/staff/factor/verify	auth:staff	Verify the factor challenge OTP

C.5 Staff Profile

Method	Path	Auth	Purpose
POST	/api/staff/profile	auth:staff	Update editable staff profile fields

D. Service Integration APIs

D.1 Resolve WESB User

Method	Path	Auth	Purpose
GET	/api/service/resolve	X-Service-Key for an active site	Resolve a WESB user by wesb_user_id or email

Accepted query parameters:

• wesb_user_id
• email

D.2 Exchange Hosted Login Auth Code

Method	Path	Auth	Purpose
POST	/api/service/exchange	X-Service-Key for an active site	Exchange a one-time hosted-login auth code for trusted WESB user identity data

Accepted JSON body:

• code (required)

D.3 Auxiliary Service Token

Method	Path	Auth	Purpose
POST	/api/service/token	X-Service-Key for an active site	Issue an auxiliary lightweight token payload for a known WESB user

Accepted JSON body:

• wesb_user_id (required)