Home Frequently Asked Questions (FAQ)

Frequently Asked Questions (FAQ)

Last updated: May 2026

Common questions about the Agglestone API Suite services and how to get started.

Getting Started

Where do I get my Tenant ID?

Your Tenant ID is available in the Agglestone Portal. Log into your account at https://portal.agglestone.com to find your Tenant ID. The Tenant ID is required for all API calls and is used to ensure complete tenant isolation across all services.

What services are available?

The Agglestone API Suite currently includes:

  • Authentication and User Management Service – OAuth2 and OpenID Connect authentication, user management, MFA, and security features
  • Messaging Service – Coming Soon
  • Workflow Management Service – Coming Soon

All services share the same tenant model and authentication system, making it easy to integrate multiple services into your application.

What are the service base URLs?

  • Authentication and User Management Service: https://auth.agglestone.com/

How do I authenticate API requests?

All API requests require a valid JWT access token in the Authorization: Bearer {token} header or an API Key. JWT tokens are issued by the Authentication and User Management Service and can be used across all Agglestone services. The token must include:

  • sub or userId claim containing the user ID
  • tenantId claim (or it will be extracted from the URL path)
  • Valid expiration time

The API Key is available on the Agglestone Portal https://portal.agglestone.com and should only be used for backend-to-backend calls.

Where can I find API documentation?

Interactive API documentation is available via Swagger UI for each service:

 

You can explore all endpoints, view request/response schemas, and try out the APIs interactively.

Authentication and User Management Service

What authentication protocols are supported?

The Authentication and User Management Service implements:

  • OAuth2 (RFC 6749) authorization code flow with PKCE
  • OpenID Connect for identity layer on top of OAuth2
  • OpenID Connect Discovery for automatic client configuration
  • JWTs (RFC 7519) for secure, verifiable tokens

Do I need to use a specific client library for authentication and login?

No, you can use any standard OAuth2/OIDC client library. We recommend oidc-client-ts@^3.4.1 for TypeScript/JavaScript applications, but any library that supports OAuth2 and OpenID Connect will work. The service uses OpenID Connect Discovery, so client libraries can automatically discover all endpoints and configuration.

What is multi-factor authentication (MFA)?

MFA and 2FA adds an extra layer of security using time-based one-time passwords (TOTP). Users can set up MFA by scanning a QR code with their authenticator app (Google Authenticator, Microsoft Authenticator, Authy, etc.). Once configured, users are prompted for their authenticator code during login.  2FA is also available with a code being sent to a user’s email address.

What is Monthly Active User (MAU)?

Monthly Active User (MAU) is a measurement for the number of unique users are actively using a service in a given month.  We calculate MAU by recording unique logins and refreshing of tokens.  If the same user account logs in or refreshes their token multiple times in the month, this is recorded as only a single active user within the month.

Can I customize the login pages?

Yes! You can customize the HTML for login pages, password reset pages, and MFA setup screens to match your application’s branding. Custom HTML is fully supported, but JavaScript is not allowed on these pages for security reasons.

How do I validate JWTs in my backend?

JWTs issued by the Authentication and User Management Service can be validated in any backend that supports JWT verification. The service provides JWKS (JSON Web Key Set) endpoints for key discovery. Integration guides are available for ASP.NET Core, Node.js, Python, Java, and Go.

Multi-Tenant Architecture

How does multi-tenancy work?

Each tenant is completely isolated across all services:

  • All data (users, chats, messages, notifications) is tenant-scoped
  • Users can only access data within their tenant
  • Configuration and settings are tenant-specific
  • No cross-tenant data access is possible

This ensures complete data isolation and security between different organizations using the services.

Is my data secure and isolated?

Yes. The multi-tenant architecture ensures:

  • Complete data isolation between tenants
  • Tenant-scoped authentication and authorization
  • Separate configuration and settings per tenant
  • No possibility of cross-tenant data access

Integration

What client libraries are recommended?

For Authentication:

  • OAuth2/OIDC: oidc-client-ts@^3.4.1 for TypeScript/JavaScript, or any standard OAuth2/OIDC client library

Can I integrate these services into mobile apps?

Yes! All services work with:

  • Web applications (browser-based)
  • Mobile web applications
  • Native mobile apps (iOS, Android)
  • Desktop applications

Use standard OAuth2/OIDC libraries for authentication, available for most platforms.

What programming languages are supported?

The services are language-agnostic. You can integrate using any language that supports:

  • HTTP/REST API calls
  • OAuth2/OIDC client libraries (for authentication)

Code examples are provided in TypeScript, C#, and Python, but the APIs work with any language.

API Usage

Can I use API keys instead of JWT tokens?

Both services support API key authentication for server-to-server scenarios. API keys can be used when making requests on behalf of users or for service-to-service communication. Check the API documentation for each service for details on API key usage.

Troubleshooting

I’m getting a 401 Unauthorized error. What should I check?

  1. Ensure your JWT token is included in the Authorization: Bearer {token} header
  2. Verify the token is not expired – you can use a service like https://www.jwt.io/ to decode and view JWT details including expiration time
  3. Check that the token includes the required claims (sub or userId, and optionally tenantId)
  4. Ensure the token was issued by the Agglestone Authentication and User Management Service
  5. Verify the token signature is valid (check JWKS endpoint if validating in your backend)

I’m getting a 403 Forbidden error. What does this mean?

A 403 error typically means:

  • The tenant ID in the URL doesn’t match your authentication
  • You’re trying to access resources you don’t have permission for
  • You’re trying to access another user’s data
  • Your user doesn’t have the required permissions for the requested operation

How do I test my integration?

  1. Use the Swagger UI for each service to test API endpoints interactively
  2. Check the integration guides for code examples
  3. Use browser developer tools to inspect network requests and WebSocket connections
  4. Monitor network requests to verify authentication and API calls
  5. Test with multiple browser tabs or devices to verify multi-device scenarios

Resources

Where can I find code examples?

Code examples are available throughout the integration guides:

Examples are provided in TypeScript, and some guides include C# and Python examples.

Where can I manage my tenant settings?

All tenant settings can be managed through the Agglestone Portal. This includes:

  • Tenant configuration
  • User management
  • Security settings
  • Service-specific configurations

Where can I get more help?

—

Can’t find what you’re looking for? Check out the service overviews or integration guides for more detailed information.