API Tokens

The IAM service provides a full API token system designed for machine-to-machine (M2M) communication and external integrations.

API tokens are long-lived credentials stored hashed with sha-256 in MySQL. Each token is associated with a user, scoped by privilege level, optionally restricted to specific IP addresses, and tracked with usage metadata.

The raw token is only returned once during creation and must be stored securely by the client.

To create a token, rotate, and perform any other related sensitive action, the session needs to be fully authenticated. To create, rotate, or perform any other sensitive management action on a token, the user's session must be fully authenticated. To consume a token, the client simply provides the valid token, and your API verifies it against the required privilege scope.

If IP restrictions are in place, the token is expired, or the privilege scope is insufficient, the request will be rejected.

Each API token consists of four parts:

• prefix - configurable identifier
• random - 64-byte cryptographically value
• checksum - SHA-256 derived integrity check
• publicId - A public identifier that lets clients reference a token for dashboard actions without exposing the secret.

This structure allows the service to:

• Reject malformed tokens instantly and before DB lookup
• Prevent timing attacks using safe comparisons
• Validate integrity without exposing sensitive data

The goal of this system is to securely authenticate M2M access to your resources, APIs, and data, while remaining flexible enough to support custom business logic.

It achieves that by:

• Keeping the privileges abstract: The system doesn't know what a privilege of demo means to your app. But it knows that if a token with a privilege of demo is created, it should fail verification on a privilege of full. This allow your app to enforce RBAC, feature flags, tiered APIs, etc.
• Optional constraints: Expiry, IP restrictions, prefixes are all optional. Your app or your clients must explicitly opt-in.
• Configurable rate limiting: It enforce rate limits only on failed verification attempts. Sucessfull verification rate limits are opt-in, or should be enforces by your clients.
• Two modes: A library mode, when your install the service via npm and call the functions directly. Or as a service mode, you call the HTTP routes.

Documentation