Home Documentation Authentication and User Management Service Integration Guides Quick Start Guide

Quick Start Guide

Last updated: January 2026

Welcome to the Agglestone Authentication and User Management Service integration guide. This quick start will help you get OAuth2 and OpenID Connect authentication working in your application in minutes.

Getting Started

The Agglestone Authentication and User Management Service is available at https://auth.agglestone.com/ and uses standard OAuth2 and OpenID Connect protocols.

Don’t have your Tenant ID yet? Log into your account at https://portal.agglestone.com to find your Tenant ID. Then replace {tenantId} or your-tenant-id in the examples below with your own Tenant ID.

Using a Client Library (Recommended)

The easiest way to integrate authentication into your application is to use a standard OAuth2/OIDC client library. We recommend oidc-client-ts@^3.4.1 for TypeScript applications. This client-side library handles PKCE generation, discovery endpoint configuration, token storage, and automatic token refresh – all the client-side OAuth2/OIDC complexity is handled for you.

npm install oidc-client-ts@^3.4.1

> 🤖 Quick Integration Tip: Why not point your favourite AI software development tool at this page, and tell it you want to add Agglestone Authentication and User Management Service to your application – speed up development, with the security of battle tested backend services!

Here’s a basic setup to get you started:

// Install: npm install oidc-client-ts@^3.4.1
// Configure OAuth2 client using automatic discovery
import { UserManager, WebStorageStateStore, User } from 'oidc-client-ts';

const tenantId = 'your-tenant-id'; // Get this from https://portal.agglestone.com
const userManager = new UserManager({
  authority: 'https://auth.agglestone.com/tenant/' + tenantId + '/v2.0/Auth',
  client_id: tenantId,
  redirect_uri: 'https://yourapp.com/callback', // Where users return after login (this page must include the callback code below)
  response_type: 'code', // PKCE flow
  scope: 'openid profile email',
  automaticSilentRenew: true,  // Automatically refreshes tokens before they expire
  userStore: new WebStorageStateStore({ store: window.localStorage }) // persist tokens in localStorage
});

// Login button handler - add this to your Login button
async function handleLogin() {
  await userManager.signinRedirect();
}

// Handle callback on your https://yourapp.com/callback page
const user = await userManager.signinRedirectCallback();

// Make API calls - add bearer token manually (for example to get a list of users)
const response = await fetch('https://auth.agglestone.com/tenant/' + tenantId +'/v2.0/Users', {
  headers: {
    'Authorization': 'Bearer ' + user.access_token
  }
});

What the oidc-client-ts library handles automatically:

  • Discovery endpoint configuration (automatically finds all endpoints)
  • PKCE code generation and validation
  • Token storage and management
  • Automatic token refresh before expiry
  • Login redirect and callback handling

What you need to implement:

  • Point your login button to handleLogin()
  • Add Authorization: Bearer {token} headers to your API calls
  • Handle 401 errors in responses from your API calls (check if token expired, refresh token if needed, retry request, and return to login if 401 persists)

The client library typically handles token refresh automatically, but you’ll need to handle cases where tokens have been invalidated (for example, if a user was away for an extended period or if tokens were revoked).

What Happens When a User Clicks Login

When a user clicks the login button in your application, here’s what happens behind the scenes:

  1. Discovery and Configuration: When signinRedirect() is called, the oidc-client library automatically retrieves the OpenID Connect discovery document from https://auth.agglestone.com/tenant/{tenantId}/v2.0/Auth/.well-known/openid-configuration to self-configure with the correct authorization, token, and other endpoint URLs. This discovery metadata is typically cached after the first call to improve performance.
  2. Redirect to Login Page: The user’s browser is redirected to the Agglestone Authentication and User Management Service secure login page, hosted at https://auth.agglestone.com/tenant/{tenantId}/v2.0/Auth/authorize.
  3. User Authentication: The user enters their username and password on the secure login page.
  4. Password Reset Check: If the user is required to reset their password (configured in the Agglestone Portal), they’ll be prompted to set a new password before proceeding.
  5. Multi-Factor Authentication Check: If MFA is enabled for the user (configured in the Agglestone Portal), they’ll be prompted to set up MFA by scanning a QR code with their authenticator app if they haven’t already done so, or to enter their authenticator code if their MFA is already configured.
  6. Authorization Code Exchange: Once authentication is complete, the Agglestone Authentication and User Management Service redirects the user back to your redirect_uri with an authorization code. Your client library then automatically exchanges this authorization code for tokens at the Agglestone Authentication and User Management Service token endpoint.
  7. Token Storage: The client library receives and stores the following tokens in localStorage or sessionStorage (depending on your configuration):
    • Access Token (JWT) – Used to authenticate API requests
    • Refresh Token – Used to obtain new access tokens when they expire
    • ID Token (JWT) – Contains user identity information (if openid scope is requested)
  8. User Returns to Your App: The user is now authenticated and returned to your application. The application can then use the access token to make authenticated API calls on their behalf, and use the refresh token to renew the access token when it exires.

All of this happens automatically when you use a standard OAuth2/OIDC client library like oidc-client-ts. The library handles the redirects, code exchange, and token storage for you.

Making your First API Call

Once you have authenticated a user and obtained an access token, you can make API calls to the Agglestone Authentication and User Management Service. For example, to retrieve a list of users, you would call:

https://auth.agglestone.com/tenant/{tenantId}/v2.0/Users

Example: Let’s say your Tenant Id is 79199f3a-6669-4a21-ac5f-5dec93d90b57, then the call to get list of Users would be:

https://auth.agglestone.com/tenant/79199f3a-6669-4a21-ac5f-5dec93d90b57/v2.0/Users

Note: This call can only be made by an admin user.

For more information on managing users and groups, see Users and Groups Management.

> 📚 API Documentation: For detailed API documentation, request/response schemas, and to try out the endpoints interactively, visit the Swagger UI.

—

Next Steps

Once you have basic authentication working, you can: