General OAuth Setup

It also explains one very important rule:

• always link your own user accounts to the stable XWMS id sub
• never rely on the email address as the main key (emails can change)

If you want ready‑made examples for specific languages, see:

• JavaScript / Node.js
• PHP
• Laravel
• Python

🔍 What this prompt should generate

When you paste the prompt below into an AI, it should build a small, but complete example project that:

• starts the login flow with XWMS (sign-token)
• redirects the user to the XWMS login page
• handles the callback and verifies the token (sign-token-verify)
• reads the user data (including sub)
• shows how to link that sub to a local user in your database

🧠 The Complete Prompt for AI

Copy‑paste this text into your AI chat.
Then replace [your programming language] with something like:

• “Node.js (Express)”
• “Python (FastAPI)”
• “PHP (plain)”
• “C# (ASP.NET Core)”

You are an AI assistant for developers. Your task is to generate a COMPLETE, WORKING EXAMPLE APP that integrates with the XWMS Authentication API.

The user will replace [your programming language] with their desired programming language or framework.

If the user did NOT replace [your programming language], politely ask them which language they want to use first, and wait.

---

## 1. GOAL

Build a runnable example project in [your programming language] that connects to the XWMS authentication system.

The project must show how to:
- Start the authentication process (`sign-token`)
- Redirect the user to the XWMS login page
- Handle the callback and verify the token (`sign-token-verify`)
- Read the returned user data (including the stable id `sub`)
- Link this `sub` to a local user account in a database

IMPORTANT: explain clearly that `sub` is a stable user id that never changes, and that the app should NOT rely on email as the primary key for linking users. Email is optional and may change; `sub` is the professional way to link accounts.

---

## 2. API DETAILS

Use these XWMS API endpoints:

1. GET  https://xwms.nl/api/info
   - Fetch basic service info (for a simple health check).

2. POST https://xwms.nl/api/sign-token
   - Start authentication.
   - JSON body must contain at least:
     - `redirect_url`: URL in the client app that will receive the token.

3. POST https://xwms.nl/api/sign-token-verify
   - Verify the token that was returned to the client’s redirect URL.
   - JSON body must contain:
     - `token`: the token from the query string

Required headers for POST requests:

  X-Client-Id:     <client id from XWMS>
  X-Client-Secret: <client secret from XWMS>
  X-Client-Domain: <client domain or domain id>
  Accept:          application/json

Use example values like:

  redirect_url: http://localhost:3000/xwms/validateToken

The real values should come from environment variables.

---

## 2.1 Response format (always JSON)

All XWMS responses use the same envelope:

```json
{
  "status": "success",
  "message": "Human readable message",
  "data": { "..." : "payload" }
}

• status is success or error
• message explains what happened
• data contains the payload for that endpoint

2.2 sign-token response (start auth)

When you call sign-token, XWMS responds with:

• client_id (string)
• token (string)
• email (string, if available)
• expires_at (ISO 8601 string)
• url (string, the login/redirect URL)

The redirect URL is typically handled by your helper, so you rarely need to use it manually.

2.3 sign-token-verify response (user data)

When you verify the token, XWMS returns user data in data:

• sub (string, stable user id)
• name (string)
• given_name (string)
• family_name (string or null)
• email (string)
• email_verified (boolean)
• picture (string URL)

Always link users by sub.

3. WHAT YOU MUST GENERATE

As the AI, generate:

1. A small, runnable demo app (not just code fragments).
2. Installation commands (e.g. pip/composer/npm/dotnet).
3. A suggested folder structure.
4. A .env (or equivalent) with:
   • XWMS_CLIENT_ID
   • XWMS_CLIENT_SECRET
   • XWMS_CLIENT_DOMAIN (or DOMAIN_ID)
   • XWMS_REDIRECT_URI
   • XWMS_API_URL (for example https://xwms.nl/api/)
5. A main server file (like app.js, main.py, Program.cs, …) with routes:
   • /xwms/auth → calls sign-token and redirects to XWMS
   • /xwms/validateToken → receives token, calls sign-token-verify, and processes the user data
   • / → shows a “Login with XWMS” link or button
6. Clear comments explaining each important line.
7. Clear instructions on how to run the app locally.
8. Basic deployment tips (for example “use environment variables on the server”).

4. ACCOUNT LINKING REQUIREMENTS (VERY IMPORTANT)

When describing how to handle the response from sign-token-verify, you MUST:

1. Show an example JSON response that contains at least:
   { "status": "success", "message": "Successful authenticated", "data": { "sub": "xwms-user-1234", "email": "user@example.com", "name": "Jane Doe", "email_verified": true } }
2. Explain that:
   • sub is the stable XWMS user id.
   • email may be missing or may change over time.
3. Implement logic that:
   • Tries to find an existing local user by sub in a table like xwms_connections (or equivalent).
   • If found: logs that user in.
   • If not found: creates a new local user (name/email/picture) and stores a record linking sub to that new user.
4. Describe this in very simple terms as well, for example:
   • “Think of sub as the number on a library card. Even if the person moves house or changes email, the card number stays the same.”

5. SECURITY NOTES

Include a short section that:

• Explains that secrets must be stored in .env or a secure config store.
• Warns against committing secrets to Git.
• Recommends using HTTPS in production.
• Shows how to handle missing/invalid tokens without crashing the app.

6. EXPECTED OUTPUT SHAPE

Your final answer should include:

• A short explanation of the flow in natural language (1–2 paragraphs).
• The install commands.
• The .env example.
• The complete main server file.
• Any extra files that are strictly needed (for example a minimal database helper or in‑memory store to show the sub → user linking).

Explain everything in a friendly way, but make the code production‑grade.

---

## ✅ Summary

- This page gives you a “super prompt” that any coding‑capable AI can use
  to generate a complete XWMS OAuth example in **any language**.
- The prompt stresses the professional way of linking accounts:
  **always by `sub`, never by email alone**.
- For concrete examples without an AI in the loop, use the language‑specific
  pages in this section (JavaScript, PHP, Laravel, Python).