Authentication

​

Overview

Moss uses multiple authentication mechanisms depending on the context:

---

​

JWT Authentication

JWT (JSON Web Token) authentication provides the highest security for SDK integrations.

​

How It Works

1. Your backend generates a signed JWT for each user session
2. The SDK includes this token in API requests
3. Moss validates the signature, expiration, and claims
4. Access is granted only if all checks pass

​

Token Structure

Moss JWTs include the following claims:

​

Security Features

• HS256 Signing - By default, tokens are signed using HMAC-SHA256 with your application’s secret key
• Expiration Enforcement - Tokens must include valid exp claim
• Key Rotation Support - Multiple active signing keys with scheduled revocation
• Constant-Time Validation - Signature verification uses timing-safe comparison

​

Signing Schemes

Moss supports two signing schemes per application: With asymmetric signing you generate the keypair yourself and register only the public key with Moss. The private key never leaves your infrastructure, so Moss holds no material that could be used to mint tokens on your behalf. Each registered key is pinned to its algorithm, and rotation requires registering a new keypair rather than re-registering a retired one.

​

Key Management

Each application can have multiple JWT signing keys:

• Key ID (kid) - Unique identifier included in token header
• Active Status - Keys can be deactivated without deletion
• Scheduled Revocation - Set future revocation dates for graceful rotation
• Last Used Tracking - Monitor key usage for security auditing

---

​

Dashboard Authentication (Clerk)

The Moss Dashboard uses Clerk for authentication, providing enterprise-grade SSO capabilities.

​

Features

• OAuth Integration - Sign in with Google, GitHub, or email
• Organization Support - Multi-tenant access with role-based permissions
• Session Management - Secure session tokens with automatic refresh
• MFA Support - Optional multi-factor authentication

​

Organization-Based Access

All Dashboard operations are scoped to your organization:

• Applications belong to organizations
• Users can be members of multiple organizations
• Switching organizations changes your visible applications
• API calls from Dashboard include organization context in JWT

---

​

Multi-Tenancy Security

Moss enforces strict tenant isolation at every layer:

​

Database Level

Every query is scoped to the requesting organization, so records belonging to other organizations are never returned.

​

API Level

• JWT tokens include organization ID in claims
• API endpoints verify organization ownership before access
• Cross-organization requests are rejected with 403 Forbidden

​

Audit Level

• Access attempts to other organizations are logged
• Security alerts can be configured for suspicious patterns

---

​

Session Authorization

Beyond authentication, Moss verifies authorization for every request:

​

Session Verification

1. User Ownership - Sessions belong to specific users
2. Application Scope - Sessions are bound to applications
3. Composite Keys - Foreign key constraints enforce data integrity

​

Access Patterns

---

​

Security Recommendations

​

For SDK Integration

1. Use JWT authentication for production deployments
2. Implement token refresh before expiration
3. Set short token lifetimes (15-60 minutes recommended)
4. Use HTTPS for all API communication

​

For Dashboard Access

1. Enable MFA for all team members
2. Review organization members regularly
3. Use SSO if available in your organization
4. Audit access logs periodically

---

​

Next Steps