Authentication and User Management

Last updated: December 2025

Welcome to the API Suite Portal 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 automatically configures everything 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. It 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

Here’s the basic setup:

import { UserManager } 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',
  scope: 'openid profile email',
  automaticSilentRenew: true  // Automatically refreshes tokens before they expire
});

// Login button - just call this!
await userManager.signinRedirect();

// Handle callback on your /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 (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: Library normally 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

Check out the Quick Start guide for complete examples! 🚀

—

More Information

New to our API? Start here:

👉 Quick Start – Get authentication working by stepping through our copy-paste examples

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

Need Help?

Check the detailed guides in this documentation
Review the code examples for your programming language
Login to https://portal.agglestone.com for additional help

Agglestone Labs

Authentication and User Management

🚀 Very Quick Start

The OpenID Connect Discovery Endpoint

Using a Client Library (Recommended)

More Information

Documentation Pages

Quick Start

OAuth2 and OIDC Overview

Integration Guide

User and Group Management

API Keys vs JWT Tokens

Backend-For-Frontend (BFF)

Code Examples

What You Need

Security

Need Help?