Home Frequently Asked Questions (FAQ)

Frequently Asked Questions (FAQ)

Last updated: January 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 – Real-time chat functionality and notification delivery

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/
  • Messaging Service: https://messaging.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 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.

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.

Messaging Service

What is the difference between Chat and Notifications?

Chat is for real-time, bidirectional conversations between users. Chat messages are sent to chat channels with multiple members, delivered instantly via WebSocket, and part of ongoing conversations with full history.

Notifications are one-way messages stored in a user’s personal inbox. Notifications are sent to individual users, stored for later reading, can be marked as read/unread, and can optionally be delivered via email.

Can I use both Chat and Notifications in my application?

Yes! Many applications use both features. Chat for real-time user conversations, and Notifications for system messages, alerts, and important announcements. Both features use the same WebSocket connection and authentication.

What technologies does the Messaging Service use?

The Messaging Service is built on:

  • WebSockets (RFC 6455) for real-time bidirectional communication
  • SignalR for reliable WebSocket connections with automatic reconnection
  • REST APIs following standard HTTP conventions
  • JWT Authentication for secure, token-based access control

Do I need to use SignalR, or can I use raw WebSockets?

While the service uses SignalR on the server side, you can use any WebSocket client library that supports JWT authentication and the SignalR protocol. We recommend using the official SignalR client libraries for the best experience, as they handle reconnection, protocol negotiation, and error handling automatically.

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

Do I need to use both services together?

No, you can use the services independently:

  • Use only the Authentication and User Management Service for authentication and user management
  • Use only the Messaging Service for chat and notifications (but you’ll still need JWT tokens from the Authentication service)
  • Use both services together for a complete solution

The Messaging Service requires JWT tokens from the Authentication and User Management Service, but you can use the Authentication service independently.

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

For Messaging:

  • SignalR: @microsoft/signalr@^10.0.0 for TypeScript/JavaScript
  • HTTP Clients: Any standard HTTP client library (fetch, axios, HttpClient, requests, etc.)

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 and SignalR client libraries for messaging, 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)
  • WebSocket/SignalR clients (for messaging)

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

My WebSocket connection keeps disconnecting. What should I do?

  1. Ensure your JWT token hasn’t expired (tokens expire after a set time)
  2. Implement token refresh logic to get a new token before expiration
  3. Use the SignalR client library’s automatic reconnection feature
  4. Check your network connection and firewall settings
  5. Verify the WebSocket URL and authentication are correct

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.