Getting Started with XWMS Clients & OAuth

This page is your starting point for connecting an external app (website, dashboard, mobile app, …) to XWMS using OAuth.

You will:

• create or open a Client (Partner) in XWMS
• configure domains, scopes and secrets
• learn where to find the values your app needs (client id, secret, domain, …)
• see where to go for language‑specific code examples

Even if you are not a developer, this page should help you understand what is happening and what you need to give to your developers.

1. Prerequisites

• You have an XWMS account and can log in.
• You have at least one Client (Partner) or you can create one.
• For OAuth you need a paid account to access the Clients dashboard.

If needed, see the user login docs first:
Login to XWMS

2. Open the “My Clients” dashboard

1. Log in to XWMS.
2. Go to your Account Dashboard.
3. Click “My Clients” in the navigation.

If you have no clients yet, XWMS will ask you to create your first one.

3. Create or select a Client

To create a new client:

1. Click “Create Client” (or similar).
2. Enter a clear name, for example mycompany-main-app.
3. Confirm.

You will be taken to the Client Dashboard where you can configure:

• Integrations (Domains, Scopes, Secrets, Users)
• Verification Center
• Members & Roles

This Client represents one “integration” or “partner application”.

4. Configure Integrations for OAuth

Open the Integrations section for your client.
Here you’ll configure three things that every OAuth integration needs:

• Domains – where your app lives and where users are sent back to.
• Client Scopes – what your app is allowed to see or do.
• Client Secrets – keys used to prove that it’s really your app calling XWMS.

4.1 Domains

1. Go to Integrations → Domains.
2. Click “New Domain”.
3. Fill in:
   • Root Domain – without protocol, e.g. example.com
   • Server IP Address – IP of your server (if applicable)
   • Internal Name – optional label for yourself
4. Save.

After saving, you can configure details like:

• Domain ID – unique identifier used by XWMS
• Logo – domain‑specific logo
• Fallback URI / Response – where to send users if something goes wrong

Important toggles:

• Allow Login – must be enabled for OAuth login.
• Allow API – must be enabled to call XWMS APIs from this domain.
• Active – the domain must be active.
• Primary Domain – optional, marks the main domain.
• Test Mode – mark as test environment if this is not production.

You will later give the Domain (or Domain ID) to your app/config.

4.2 Client Scopes

Scopes describe what your app is allowed to access.

1. Go to Integrations → Client Scopes.
2. Click “New Client Scope”.
3. Select the scopes you need, such as:
   • read basic user profile
   • access address information
   • read providers
   • other business‑specific scopes
4. Save.

Only the scopes you enable here can be used by your OAuth / API integration.

4.3 Client Secrets

Client secrets are like passwords for your application, not for the user.

1. Go to Integrations → Client Secrets.
2. Click “New Secret”.
3. Optionally provide:
   • a label (for example production-backend),
   • an expiration date.

If you leave these empty:

• the secret will be named Standard Key,
• it will be active immediately.

You will later copy this secret into your application’s .env file.

4.4 Link secrets to domains

To allow a secret to be used from a specific domain:

1. Open the Domain.
2. Go to Secret Connections (or similar).
3. Click “Link Secret” and choose the secret.

Now calls from that domain using that secret are recognised as valid.

5. Where your developers get the technical details

Once your Client is configured, your developers need:

• Client Id
• Client Secret
• Domain / Domain Id
• Redirect URL – the URL where XWMS should send users back after login
• The XWMS API URL – usually https://xwms.nl/api/

For code examples and detailed flows, direct them to:

• General OAuth Setup (AI prompt)
• JavaScript / Node.js Guide
• PHP Guide
• Laravel Guide
• Python Guide

All those pages explain the same idea:

• start auth with sign-token
• user logs in on XWMS
• XWMS redirects back with a token
• your app calls sign-token-verify and receives user data, including sub
• your app links that stable sub to a local account

6. Client Users, Verification and Roles (optional but important)

Client Users

Under Integrations → Users you can:

• see which XWMS users have logged in via your client/domain
• send access requests or test user requests

When a user accepts such a request, your client may gain access to additional scopes (depending on your partnership level).

Verification Center

In the Verification Center you can apply to become a Verified Partner:

1. Create a new verification request.
2. Select the domains and scopes you need.
3. Add notes to explain your use case.

The XWMS team will review and approve/reject the request. Verified partners can receive more powerful scopes.

Members & Roles

The Members and Roles sections control who in your organisation can manage the client:

• Roles define permissions (view users, manage scopes, etc.).
• Members assign those roles to actual XWMS accounts.

This has no direct impact on OAuth tokens, but it is important for who is allowed to change settings.

7. Summary

If you follow this page first and then open one of the OAuth guides, you’ll have everything you need to build a clean, professional login flow with XWMS.