Home Documentation Authentication and User Management

Authentication and User Management

Last updated: December 2025

Welcome to the Agglestone API Suite documentation for authentication and user management. This guide will help you integrate authentication and user management into your own applications.

🚀 Very Quick Start

Want to get started less than 60 seconds? Here’s the fastest path to authentication nirvana! ✨

Our authentication service lives at https://auth.agglestone.com/ and it’s ready to make your life easier. The magic happens through our OpenID Connect discovery endpoint, which together with a client library, enables most things to be configured automatically for you.

The OpenID Connect Discovery Endpoint

Your tenant’s discovery endpoint is located at:

https://auth.agglestone.com/tenant/{tenantId}/v2.0/Auth/.well-known/openid-configuration

Example: Let’s say your Tenant Id is 79199f3a-6669-4a21-ac5f-5dec93d90b57, then your discovery URL would be:

https://auth.agglestone.com/tenant/79199f3a-6669-4a21-ac5f-5dec93d90b57/v2.0/Auth/.well-known/openid-configuration

Don’t have your Tenant Id yet? No worries! Just log into your account at https://portal.agglestone.com and you’ll find it there. Then simply swap out the GUID in the URL above with your own Tenant Id. Easy peasy! 🎯

Using a Client Library (Recommended)

The easiest way to integrate your client into our auth service is to use a client-side library like oidc-client-ts@^3.4.1. The client library handles most of the client-side OAuth2/OIDC stuff for you – PKCE generation, discovery endpoint configuration, local token storage, and automatic token refresh!

npm install oidc-client-ts@^3.4.1

Why not point your favourite frontend AI software development tool at this page, and tell it you want to add Agglestone’s authentication and user management to your application – speed of development, with the security of battle tested backend services!

Here’s the basic frontend setup:

import { UserManager, WebStorageStateStore, User } from 'oidc-client-ts';

const tenantId = 'your-tenant-id-here'; // 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 handle and store the tokens)
  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
});

// Add this to your Login button
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
  }
});

Check out the Integration Guide for complete examples! 🚀

What the oidc-client-ts library handles automatically:

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

What you still need to do:

  • 🔧 Point your login button to userManager.signinRedirect()
  • 🔧 Add Authorization: Bearer {token} headers to your API calls
  • 🔧 Handle 401 errors (check if token expired, refresh if needed, retry request)

(Note: Libraries often auto-refreshes before expiry, but you’ll need to handle invalidated tokens if user was away or backend revoked them)

Using tokens with your own backend? 🔐

The Auth Service JWT tokens don’t just work with other Agglestone API Suite services. You can also use them with your own backend services, to ensure users have been authenticated and have the right permissions. When doing this, we recommend using standard JWT validation features available in many programming languages. For ASP.Net Core, use the AddJwtBearer middleware which provides built-in validation including signature verification (via ValidateIssuerSigningKey), issuer validation (via ValidateIssuer and IssuerValidator), audience validation (via ValidateAudience), and token lifetime checks (via ValidateLifetime).

> ⚠️ Important: If you’re validating JWT tokens in your own backend service, make sure to:

– ✅ Always verify the issuer (iss claim) matches your tenant’s issuer: https://auth.agglestone.com/tenant/{tenantId}/v2.0/Auth (where {tenantId} is your tenant Id)

– ✅ Validate the signature using the public key from jwks.json, discoverable via https://auth.agglestone.com/tenant/{tenantId}/v2.0/Auth/.well-known/openid-configuration, to ensure tokens haven’t been tampered with

– ✅ Reject any expired tokens by validating the exp claim

—

Next Steps

Once you have the basic authentication system integrated with your application, it’s then time to add users and groups with Agglestone’s Users and Groups Management. Learn how to manage users and groups in your tenant. Create, update, and manage user accounts and organize them into groups for access control.

More Information

Learn about OAuth2 and OIDC Connect, why we use these standards, and how our implementation is compliant with industry standards. This guide explains the concepts and shows you which client libraries you can use.

The Agglestone authentication and user management service can work with both API Keys and JWT Tokens. Generally, API Keys should be used for server-to-server communication at the system level, while JWT Tokens should be used for actions to represent the user, and coming from the frontend to the backend.

If you want to get advanced, and you have your own backend services, take a look at how Agglestone’s auth service can be used with the Backend-For-Frontend (BFF) pattern for keeping your frontend simple and secure. With BFF, your backend handles all OAuth2/OIDC complexity while your frontend just makes simple API calls.

Looking for a seamless user experience? You can Customise the Login Screen with your own html and css styles. A secure login page, hosted by Agglestone, but with your branding.

What You Need

Before you start, make sure you have:

  • Tenant Id – Your OAuth2 Client Id is your Tenant Id (login to https://portal.agglestone.com to view your Tenant Id)
  • Base URL – https://auth.agglestone.com/tenant/{tenantId}/v2.0/Auth
  • Redirect URI – Where users return after login (e.g., https://yourapp.com/callback)

Security

Our implementation follows industry best practices:

  • ✅ OAuth2 RFC 6749 compliant
  • ✅ OpenId Connect Core 1.0 compliant
  • ✅ PKCE (RFC 7636) required for all authorization code flows
  • ✅ State parameter for CSRF protection
  • ✅ Secure token storage and rotation
  • ✅ HTTPS only in production