Authentication & Access
JWT auth, organizations, access tags, API keys, OAuth accounts, service accounts, 2FA.
This page covers user authentication, organization management, permission systems, API keys, OAuth accounts, and service accounts.
Authentication
JWT Tokens
The platform uses JWT-based authentication. Users log in with email and password, and receive short-lived access tokens that are sent with each API request. Tokens refresh automatically.
Token Refresh
Access tokens refresh automatically when they expire.
Signup Flow
Admins invite new users by email. Invitees receive a signup link to create their account and join the organization.
Two-Factor Authentication (2FA)
The platform supports TOTP-based two-factor authentication. Users can enable 2FA by scanning a QR code with an authenticator app such as Google Authenticator or Authy. Once enabled, a time-based code from the app is required at login in addition to the password. One-time backup codes are provided during setup for account recovery if the authenticator is unavailable. Each backup code can only be used once, and new codes can be regenerated (which invalidates the old set). 2FA can be disabled from account settings.
Organizations
Multi-Tenancy
Every resource belongs to an organization. Data is isolated between organizations at the middleware level -- a user in Organization A cannot see Organization B's schemas, processes, or executions.
Organization Properties
| Field | Type | Description |
|---|---|---|
id | UUID | Organization identifier |
name | string | Organization name |
description | string | Organization description |
project_status | enum | active, on_hold, completed |
logo_url | string | Organization logo |
background_url | string | Background image |
Switching Organizations
Users can be members of multiple organizations. When switching organizations, the JWT is re-issued with the new organization context.
Inviting Users
Admins invite users by email. Access tags can be pre-assigned during the invitation. The invitee receives a signup link, and the specified access tags are applied when they complete signup.
Access Tags (Permissions)
How It Works
Permissions are controlled by access tags. Each tag grants read or write access to a specific system (domain).
| System | Controls |
|---|---|
process | Processes, nodes, edges, executions |
schema | Schemas, data blocks, data points |
storage | File uploads, downloads, attachments |
dashboard | Dashboards, components, queries |
analytics | Logs, statistics, time series |
database | Database instances, tables, queries |
Permission Levels
| Permission | Allows |
|---|---|
read | View, list, export |
write | Create, update, delete (implies read) |
Tag Structure
Each access tag associates a user with a system and a permission level (e.g., write access to the process system).
Authorization Flow
Each API request goes through three checks:
- Authentication: Is the JWT valid?
- Organization: Does the user belong to the organization being accessed?
- Permission: Does the user have the required access tag for this system and permission level?
Admin Users
Users with admin: true bypass permission checks. They have full access to all systems within their organization.
Managing Tags
Admins can list, add, and remove access tags for any user. Users can view their own tags. When inviting a user, admins can pre-assign access tags that are applied when the user completes signup.
API Keys
API keys provide programmatic access to trigger processes and interact with the API without JWT authentication.
Key Properties
| Field | Type | Description |
|---|---|---|
id | UUID | Key identifier |
name | string | Human-readable name |
description | string | Purpose description |
allowedProcessIds | UUID[] | Restrict to specific processes (null = all) |
rateLimitPerMinute | int | Max requests per minute |
expiresAt | timestamp | Expiration date (null = never) |
isActive | bool | Whether the key is active |
lastUsedAt | timestamp | Last usage timestamp |
usageCount | int | Total usage count |
Creating a Key
When creating an API key, you specify a name, optional description, allowed processes, rate limit, and expiration. The full key is returned once at creation time -- store it securely, as it cannot be retrieved again.
Using a Key
API keys can be included in requests via an X-API-Key header or as a Bearer token in the Authorization header.
Revoking a Key
Revoked keys immediately stop working. Revocation cannot be undone.
Process Restriction
When allowedProcessIds is set, the key can only trigger those specific processes. Attempts to use the key with other processes are rejected with a 403.
Rate Limiting
Each key has its own rate limit (rateLimitPerMinute). Exceeding the limit returns a 429 response.
System Keys
System keys (isSystemKey: true) are admin-level keys for system operations like batch testing and monitoring. They bypass process restrictions.
External API Keys
Encrypted storage for third-party API credentials used by integration nodes and LLM providers.
Key Properties
| Field | Type | Description |
|---|---|---|
id | UUID | Key identifier |
name | string | Human-readable name |
provider | string | Provider name (e.g., "openai", "anthropic") |
encryptedKey | string | Encrypted API key |
last4 | string | Last 4 characters for identification |
isActive | bool | Whether the key is active |
metadata | JSONB | Provider-specific metadata |
Storing a Key
External keys are encrypted at rest. Only the last 4 characters are stored in plaintext for identification.
Verification
External keys can be verified by testing them against the provider's API before saving.
OAuth Accounts
OAuth accounts connect external email providers (Gmail, Outlook) for use in input and output nodes.
Account Properties
| Field | Type | Description |
|---|---|---|
id | UUID | Account identifier |
provider | enum | "gmail" or "outlook" |
userEmail | string | Authenticated email address |
encryptedToken | string | Encrypted OAuth tokens |
name | string | Display name |
Connection Flow
- User initiates OAuth from the UI (Settings > OAuth Accounts).
- Browser redirects to the provider's consent screen.
- User grants access.
- Callback URL receives the authorization code.
- Backend exchanges the code for access and refresh tokens.
- Tokens are encrypted and stored.
Token Refresh
OAuth tokens are refreshed automatically when they expire. The refresh token is used to obtain a new access token without user interaction.
Service Accounts
Service accounts enable server-to-server authentication, primarily for Gmail API access via Google Workspace domain-wide delegation.
Account Properties
| Field | Type | Description |
|---|---|---|
id | UUID | Account identifier |
provider | enum | "gmail" |
serviceAccountEmail | string | Service account email |
projectId | string | GCP project ID |
encryptedCredentials | string | Encrypted service account JSON |
allowedImpersonationTargets | string[] | Emails the SA can impersonate |
Creating a Service Account
- Create a service account in Google Cloud Console.
- Enable domain-wide delegation.
- Download the service account JSON key file.
- Upload the JSON key and configure impersonation targets in the platform.
Impersonation
Service accounts impersonate specific email addresses. The allowedImpersonationTargets list restricts which mailboxes can be accessed.
Use in Processes
In Gmail input/output nodes, select authMethod: "service_account" and specify:
- The service account ID
- The impersonation email (must be in the allowed targets list)
Security Model
Security
Passwords are securely hashed. API keys are hashed at rest. Credentials, tokens, and keys are encrypted at rest and hashed where appropriate.
CORS
CORS origins are configured per-organization. Only registered origins can make cross-origin requests.
Audit Logging
All authentication events are logged:
- Login attempts (success and failure)
- Password changes
- 2FA setup/disable
- API key creation/revocation
- OAuth account connections
Logs are queryable with appropriate filters.