Authentication
MeetLoyd supports multiple authentication methods to fit your security requirements.
Authentication Methods
| Method | Best For | Security Level |
|---|---|---|
| JWT Tokens | Web/mobile apps | High |
| API Keys | Server-to-server | High |
| SSO/SAML | Enterprise | Very High |
| OAuth 2.0 | Third-party apps | High |
JWT Authentication
Login Flow
Users authenticate with email and password. The platform issues an access token (15-minute lifetime) and a refresh token (7-day lifetime). The access token is used for all API requests, and the refresh token obtains new access tokens when they expire.
Multi-Tenant Login
If a user belongs to multiple organizations, the login response includes a memberships array. The dashboard displays a tenant picker so the user can choose which workspace to enter. See Multi-Tenant Membership for details.
Token Lifecycle
Login → Access Token (15 min) → Refresh → New Access Token. Refresh Token lasts 7 days.
| Token | Lifetime | Purpose |
|---|---|---|
| Access Token | 15 minutes | API requests |
| Refresh Token | 7 days | Get new access token |
Token Contents
Access tokens contain the user ID, email, tenant ID, role, and permissions. They are signed JWTs that can be verified without a database call.
API Keys
For server-to-server communication, MeetLoyd supports API keys with granular permissions.
Key Features
- Named keys for easy identification and management
- Granular permissions -- scope each key to only the operations it needs
- Optional expiration -- set an expiry date for temporary integrations
- Rotation support -- create a new key, update your servers, then revoke the old one
- Usage tracking -- see when each key was last used
- Always use descriptive names (e.g., "prod-web-readonly")
- Limit permissions to only what is needed
- Set expiration dates for temporary integrations
- Never grant wildcard permissions
- Rotate keys regularly
Multi-Factor Authentication (MFA)
MFA adds a second layer of security using TOTP (Time-based One-Time Passwords) compatible with any authenticator app (Google Authenticator, Authy, 1Password, etc.).
Features
- TOTP-based -- works with any standard authenticator app
- Recovery codes -- 10 single-use codes generated during setup for account recovery
- Org-wide enforcement -- admins can require MFA for all users or specific roles (e.g., owners and admins only)
Role-Based Access Control (RBAC)
MeetLoyd provides 112 granular permissions across 5 tiers for enterprise-grade access control.
Built-in Roles
| Role | Description | Scope |
|---|---|---|
| Owner | Full access, billing, tenant management | Workspace |
| Admin | Full access except billing, tenant deletion | Workspace |
| AI Engineer | Technical focus: agents, tools, workflows | Workspace |
| Member | Standard access for daily operations | Team-scoped |
| Viewer | Read-only access | Team-scoped |
Role Hierarchy
Owner → Admin → AI Engineer → Member → Viewer
Roles generally inherit permissions from roles below them, but there are non-hierarchical differences -- some permissions are granted to specific roles based on function rather than strict hierarchy.
Permission Categories
| Category | Permissions | Description |
|---|---|---|
| Core Platform | 61 | Agents, apps, teams, users, billing, tools, workflows |
| Tier 1 - Critical | 16 | Secrets, schedules, memory, charters, avatars |
| Tier 2 - Compliance | 15 | Governance, audit alerts, retention, SIEM, security, access reviews |
| Tier 3 - Operational | 20 | SCIM, sessions, conversations, skills, delegation, voice, manifests |
Tenant Isolation
Multi-Tenant Architecture
Each organization (tenant) is completely isolated. Every API request is scoped to a single tenant via the JWT. There is no mechanism for a single API request to access data across tenants.
- Tenant-level database isolation
- Separate encryption keys per tenant
- Network-level segmentation
- No cross-tenant data access
Users can be members of multiple tenants and switch between them without logging out. Each switch issues a fresh JWT scoped to the target tenant. See Multi-Tenant Membership for the full model.
Authentication Troubleshooting
| Issue | Steps to Resolve |
|---|---|
| "Invalid Token" | Check token hasn't expired. Verify token is for the correct environment. Ensure token is properly formatted in the Authorization header. |
| "Permission Denied" | Check user's role has the required permission. Verify API key includes needed permissions. Check team membership for scoped resources. |
| "Account Locked" | After too many failed attempts, an admin can unlock the account from Settings > Members. |
Agent Identity
For agent-to-agent authentication and delegation, MeetLoyd provides a separate identity stack based on SPIFFE, W3C Verifiable Credentials, and OAuth 2.0 Token Exchange. This goes beyond human user authentication -- agents get cryptographically verifiable identities, signed capability badges, and short-lived delegation tokens.
See Agent Identity for the full agent identity documentation.