Whether you’re a developer building your first integration, a security professional evaluating our authentication model, or an administrator managing access for your Space, this documentation will provide the knowledge you need. Authentication forms the foundation of every interaction with the Monime platform. Before diving into implementation details, it’s essential to understand the philosophy and architecture behind our authentication system. This overview will introduce you to the key concepts and prepare you for the more detailed guides that follow.

​
Personal Access Tokens

Monime uses Personal Access Tokens (PATs) as the primary authentication mechanism for all API interactions. To understand why we made this architectural choice, let’s consider the alternatives and their limitations. Traditional username and password authentication creates several challenges in modern distributed systems. When you use the same credentials everywhere, a compromise in one location endangers all your systems. Additionally, passwords don’t naturally support the fine-grained permissions that complex systems require. You either have full access with your password, or you don’t have access at all. Another common approach is API keys—simple strings passed with each API request. While straightforward to implement, their simplicity often hides serious limitations. Their biggest weakness is that they don’t convey the identity of the caller, only that a valid key was presented. This makes it difficult to attribute actions to specific users and weakens audit trails. On top of that, API keys often grant broad, unrestricted access without scope or role-based controls, so a single leaked key can expose everything it touches. Personal Access Tokens (PATs) solve these problems by combining identity with granular control. Each PAT is tied directly to a specific user account—what Monime calls a Monimeer—so every action taken with a token is traceable back to the individual behind it.
You can issue different tokens for different applications or integrations, each with precisely the permissions it needs and nothing more. If one token is compromised, it can be revoked instantly without disrupting other tokens or integrations, and optional expiry dates ensure that unused or forgotten tokens don’t linger as security risks.

​
The Three Pillars of Monime Authentication

Our authentication system rests on three fundamental pillars that work together to provide security, flexibility, and scalability:

​
1. Multi-Tenant Architecture with Spaces

Every organization using Monime operates within its own Space—a completely isolated environment that ensures your data never mingles with others’. This isolation goes beyond simple data separation; each Space maintains its own security policies, user roles, operational rules and even test environment. The authentication system enforces these boundaries absolutely, ensuring that a token scoped for one Space can never access another Space’s resources.

​
2. Role-Based Access Through Monimeers

Within each Space, individuals are assigned specific roles that define their capabilities. These roles aren’t just labels; they’re comprehensive permission sets that determine exactly what operations each Monimeer can perform. The beauty of this system lies in its flexibility—a Monimeer might be an Owner role in one Space while having Developer role in another, perfectly modeling real-world organizational structures.

​
3. The Permission Intersection Model

This is where Monime’s authentication model becomes truly sophisticated. When a Monimeer creates a Personal Access Token (PAT), the system evaluates two separate permission sets to determine what that token can actually do:
  1. The token’s declared permission set – the specific scopes and actions the creator explicitly grants to that token at creation time. This allows the Monimeer to design tokens for narrow, purpose-built use cases—such as viewing payout details without modifying them, accessing transaction history for analytics, or checking account balances without the ability to initiate transfers—all without exposing unrelated or higher-risk capabilities.
  2. The Monimeer’s own permission set – this is the full range of actions the Monimeer is allowed to perform in a specific Space, based on their assigned role(s) granted within that Space. It acts as the upper bound for what anyPersonal Access Token created by that Monimeer can do.
In other words, the access token’s effective permissions are the intersection of these two sets. This mathematical approach ensures that access tokens are both identity-bound and context-aware. It prevents privilege escalation, enforces least privilege by design, and guarantees that no token—no matter how it is configured—can ever operate beyond the limits of its creator’s legitimate authority. API Docs Image

​
Understanding Token Types

Monime issues two distinct types of Personal Access Tokens (PATs), each designed for a specific stage of the development and operational lifecycle:
  1. Live Tokens (prefix: mon_) – These operate in the production environment, where real transactions and business operations occur. Every API call made with a live token directly interacts with production data—moving funds, updating balances, creating payouts, or triggering events with genuine business impact. Because of their direct link to real-world consequences, live tokens require strict access control, secure storage, and disciplined operational handling. They should only be issued to trusted integrations and must be treated as high-value credentials.
  2. Test Tokens (prefix: mon_test_) – These are used exclusively in the sandbox environment, a fully functional replica of production that is completely isolated from live data. Test tokens allow developers to simulate transactions, explore API endpoints, and experiment with edge cases without risking operational systems. This sandbox environment mirrors production behavior, enabling teams to validate their logic, test error handling, and perfect their workflows before moving to live operations.
By separating token types and environments, Monime ensures that experimentation and learning remain safe and consequence-free, while production remains secure and controlled. This clear boundary is fundamental to reducing risk and maintaining both development agility and operational integrity.

​
How Authentication Flows

When you make an API request to Monime, a multi-layered security process ensures that the request is both authentic and authorized before it touches any resource. This process begins the moment your request arrives with a Personal Access Token (PAT) in the Authorization header.
  1. Token structure validation – The system first checks that the token matches Monime’s required format (including its prefix, such as mon_ or mon_test_) and confirms that it exists in our database.
  2. Token status verification – The system determines whether the token is still valid, ensuring it has not expired, been revoked, or been rendered inactive by policy changes.
  3. Identity resolution – The system identifies the Monimeer who created the token, establishing the direct link between the request and the specific user account.
  4. Role and context retrieval – It then determines the Monimeer’s current role and permissions in the relevant Space, ensuring the evaluation is based on the latest organizational context.
  5. Effective permissions calculation – The system calculates the intersection between: The token’s declared permission set (the scopes the token was created with). The Monimeer’s permission set (the maximum authority the user has in that Space). This ensures no token can exceed the authority of its creator, even if it was issued with broader scopes.
  6. Operation authorization – Finally, the system verifies that the requested API operation falls within these effective permissions.
All of this happens in milliseconds, but the effect is significant: every API request is authenticated and authorized against the current permissions of the Monimeer, not just the permissions that existed at the time the token was created. This guarantees real-time enforcement of access controls, even if roles or policies change.

​
Security as a Continuous Process

Authentication security isn’t achieved through a single mechanism but through multiple layers of protection working together. Tokens are transmitted only over encrypted connections, rate limiting prevents abuse, and comprehensive audit logs track every authentication event. Moreover, the permission intersection model means that security can be dynamically adjusted. If a Monimeer’s role changes, their tokens’ effective permissions immediately reflect that change. If a security issue is discovered, tokens can be revoked instantly, with the revocation taking effect immediately across all systems.