Authentication

Overview#

Every operation in Artifi goes through a two-layer authentication system that validates identity and permissions before any tool can execute. The system supports two authentication methods transparently:

• OAuth 2.1 via Auth0 — for interactive use through Claude.ai and the admin dashboard
• API Keys — for programmatic access and Claude Desktop

Both methods produce the same security context, so the rest of the system never needs to know which method was used.

---

Authentication Methods#

OAuth 2.1 (Interactive Use)#

When you connect through Claude.ai or the admin dashboard, authentication flows through Auth0:

1. You sign in via Auth0 (email/password, Google, GitHub, etc.)
2. Auth0 issues a Bearer token
3. The token is validated against Auth0's signing keys
4. Your user profile, organization, and permissions are loaded
5. A security context is created for the session

The system supports multiple identity providers, so you can sign up with email/password on the admin dashboard and later use Google OAuth on Claude.ai -- both identities are automatically linked to the same account.

API Keys (Programmatic Access)#

For Claude Desktop, CI/CD pipelines, or any programmatic integration, API keys provide a simpler authentication path:

1. Generate an API key from the admin dashboard or via the API
2. Include the key in the X-API-Key header
3. The key is validated and your permissions are loaded
4. The same security context is created as OAuth

API keys follow the format sk_<org_id>_<random_64_chars> and can be revoked or rotated at any time.

---

Security Context#

After authentication, a security context is created containing everything needed for authorization:

This context is available to every tool call in the session, ensuring consistent authorization without repeated lookups.

---

Multi-Organization Support#

Users can belong to multiple organizations. The authentication system handles organization selection automatically:

Organization Resolution#

When you authenticate, the system:

1. Loads all organizations you belong to
2. Selects the active organization based on:
   • Pinned organization — if you specify one explicitly
   • Most recently accessed — otherwise uses your last active organization
3. Loads permissions specific to the selected organization
4. Makes all your organizations available for switching

Switching Organizations#

You can switch between organizations at any time. The switch updates your most-recently-accessed timestamp so subsequent sessions default to the new organization.

---

Linked Identity Resolution#

Users can have multiple authentication identities -- for example, signing up via email/password on the admin dashboard but using Google OAuth on Claude.ai. These produce different identity tokens, but the system links them automatically.

How It Works#

When you authenticate, the system resolves your identity in three steps:

1. Direct match — looks up your identity token directly (fastest, handles the common case)
2. Linked identities — checks if this token is linked to an existing user account
3. Email fallback — matches by email address (catches edge cases where identity was not yet linked)

When your identity is resolved via step 2 or 3, the new identity is automatically linked so future lookups resolve immediately.

---

Auto-Provisioning#

When a new user connects via Claude.ai for the first time, the system automatically provisions everything needed:

1. Organization created — named based on your email domain (e.g., acme.com becomes "Acme")
2. User account created — linked to your authentication identity
3. Organization membership — you become the organization owner
4. Admin role assigned — full administrative permissions
5. Identity linked — stored for future authentication resolution
6. Database provisioned — a complete set of tables and views cloned from the template

This enables zero-configuration onboarding -- connect the Artifi MCP connector in Claude.ai and you're ready to start. After connecting, ask Claude to begin onboarding to configure your chart of accounts, fiscal periods, tax codes, and more.

Two Provisioning Paths#

Both paths create the same records. The MCP auto-provision acts as a safety net, ensuring users are always provisioned regardless of the authentication path.

---

Permission Checking#

Permissions are checked at multiple levels:

Tool-Level Checks#

Each tool verifies that the user has the required permission before executing. For example, posting a journal entry requires accounting:post permission.

Entity Access Checks#

Tools that operate on specific legal entities verify the user has access to that entity. If a user's entity access list is non-empty, they can only access those specific entities. An empty list means access to all entities.

Workflow Permission Checks#

Write operations that go through the workflow system have permissions checked as part of workflow validation. The workflow engine verifies the user has the appropriate permissions for the operation being submitted.

---

Rate Limiting#

Rate limiting is enforced per organization to prevent abuse:

• Window: 1 hour (rolling)
• Default limit: Set per organization
• Enforcement: Checked during authentication, before any tool executes

When the rate limit is exceeded, the system returns a 429 Too Many Requests response with a Retry-After header indicating when the next request can be made.

---

Caching#

Both authentication methods use caching to maximize performance:

Token and Key Caching#

• Validated authentication results are cached for 5 minutes
• Subsequent requests in the same session skip token verification and database lookups
• Cache entries expire automatically; no manual management needed
• Permission changes take effect within 5 minutes

Signing Key Caching#

Auth0 signing keys are cached with a multi-level fallback strategy:

This ensures authentication continues working even during temporary Auth0 outages -- the system operates on cached keys for up to 24 hours.

---

OAuth Protected Resource Metadata#

Artifi implements RFC 9728 Protected Resource Metadata for automatic authorization discovery. Claude.ai uses this metadata to discover the server's authorization requirements and configure OAuth flows automatically.

Endpoints#

When an unauthenticated request arrives, the server returns a 401 Unauthorized response with a WWW-Authenticate header pointing to the metadata endpoint, enabling automatic OAuth discovery.

---

Data Isolation#

Each organization has its own database schema (company_X). The organization ID from authentication maps directly to the schema name, providing complete data isolation between organizations at the database level.

System-level entities (users, roles, API keys) are stored in a shared system schema with organization-level filtering automatically applied.

---

Best Practices#

• Use OAuth for interactive sessions through Claude.ai and the admin dashboard
• Use API keys for automated integrations, CI/CD pipelines, and Claude Desktop
• Rotate API keys regularly and revoke keys that are no longer needed
• Scope entity access to limit users to only the legal entities they need
• Monitor rate limits to ensure your organization stays within bounds
• Link identities by using the same email across authentication providers for automatic account linking