Skip to main content
Noorle supports multiple authentication methods depending on your use case. All are built on a principal-based security model that distinguishes between Users (humans) and Service Accounts (machines).

​
Which Auth Method Should I Use?

Use CaseRecommended MethodWhy
Web application with user loginOAuth 2.1Secure, user-specific access with token refresh
CLI tool or desktop appAPI Key or Device FlowSimple integration, long-lived credentials
Server-to-server automationAPI Key (via Service Account)No user interaction needed, easy to rotate
Rapid prototypingNo AuthenticationFastest setup, upgrade before production
Service-to-service (OAuth)Client CredentialsMachine-to-machine with scoped tokens

​
Quick Decision Guide

  • Building a web application? → Use OAuth 2.1 for secure, user-specific access
  • Creating a CLI tool or desktop app? → Use an API Key or the Device Flow
  • Automating a backend service? → Create a Service Account with an API key
  • Rapid prototyping? → Start with no authentication, upgrade before production
  • Third-party app integration? → Use OAuth Client Credentials for machine-to-machine
Start with the simplest method that meets your security requirements. You can always upgrade later — for example, moving from API keys to OAuth when you need user-specific access.

​
Authentication Methods

Sessions

Use case: Web UI, browser-based clients Duration: Temporary (hours/days) Setup: Sign in with email/password

API Keys

Use case: Server-to-server, integrations Duration: Long-lived (months/years) Setup: Generate in Console, rotate regularly

JWT Tokens

Use case: CLI, headless clients, APIs Duration: Short-lived (minutes/hours) Setup: Exchange via OAuth device flow

OAuth 2.1

Use case: Third-party apps, external integrations Duration: Variable (depends on flow) Setup: Dynamic client registration

​
Principal Types

Noorle uses principals to represent entities that can authenticate:

​
User (Human)

Represents a person using Noorle: 
{
  "id": "user-uuid",
  "name": "Alice Johnson",
  "email": "alice@example.com",
  "timezone": "America/New_York",
  "is_active": true,
  "last_active_at": "2024-03-22T10:30:00Z"
}
Authenticates via:
  • Session (sign in to Console)
  • JWT token (from OAuth device flow)
  • API key (personal, scoped to user)

​
Service Principal (Machine)

Represents an application, bot, or service: 
{
  "id": "service-uuid",
  "name": "DataPipeline Bot",
  "description": "Automated daily data processing",
  "timezone": "UTC",
  "is_active": true,
  "last_active_at": "2024-03-22T06:00:00Z"
}
Authenticates via:
  • API key (service-specific, scoped to service account)
  • OAuth client credentials (for service-to-service)

​
Account Roles

Principals have roles within an account (Owner → Admin → Developer → Member):

​
Security Principles

​
1. Least Privilege

Each principal has minimum permissions needed: 
Task: Connect Stripe API
  └─ Need: Connector create permission
     Not: Full account admin

Task: Debug agent logs
  └─ Need: View logs for specific agent
     Not: Access to all agents

​
2. Scoped Access

API keys are scoped to specific resources/permissions: 
{
  "key_id": "ak-xyz123",
  "scope": {
    "account_id": "account-123",
    "resources": ["gateway:abc", "agent:def"],
    "permissions": ["read", "execute"]
  }
}

​
3. Encryption

All sensitive data encrypted at rest: 
Session cookies:      HTTP-only, secure flag
API key secrets:      AES-256-GCM
OAuth tokens:         Encrypted before storage
Environment vars:     Encrypted per-gateway

​
4. Audit Trail

Every authentication event is logged: 
2024-03-22T10:30:00Z | alice@example.com | login
                     | Session: sess-123
                     | IP: 192.168.1.1

2024-03-22T10:31:00Z | alice@example.com | create_agent
                     | Agent: research-bot
                     | Session: sess-123

2024-03-22T10:32:00Z | DataBot (service)  | execute_tool
                     | Tool: web_search
                     | API Key: ak-xyz...

​
Architecture

​
Choosing Auth Method

Use CaseMethodWhy
Web UI (Console)SessionStateful, cookie-based, familiar
API integrationAPI KeyLong-lived, scoped, rotatable
CLI toolJWT TokenStateless, temporary, secure
Third-party appOAuthStandard, user-controlled, revokable
Bot/cron jobAPI Key (service)Service-specific, auditable

​
Migration Between Methods

Typically, you’ll use different methods at different layers:

​
Credential Rotation

All credentials should be rotated: API Keys: 
1. Generate new key
2. Update applications to use new key
3. Wait 24 hours
4. Revoke old key
Sessions: 
Automatic rotation:
  └─ 30 days: request re-authentication
  └─ 90 days: force logout
OAuth Tokens: 
Automatic refresh:
  └─ Access token (1 hour)
  └─ Refresh token (30 days)
     └─ Auto-refresh if expired

​
Best Practices

Never Share Secrets

API keys are passwords. Treat as secrets. Never commit to version control.

Rotate Regularly

Rotate API keys monthly. Revoke unused credentials. Audit activity.

Scope Appropriately

API key for reading logs? Don’t make it admin. Least privilege always.

Monitor Activity

Check audit logs regularly. Watch for unusual activity. Alert on failures.

​
Common Patterns

​
Pattern 1: User + API Key

Developer (you): 
Console: Sign in with email/password (Session)
API: Generate personal API key for scripts

​
Pattern 2: Service Account

Bot/cron job: 
Create service principal "DataBot"
  └─ Generate API key (long-lived)
  └─ Scoped to specific agents/gateways
  └─ Rotated monthly

​
Pattern 3: Third-Party App

External SaaS integration: 
User: Authorizes app via OAuth
  └─ User remains in control
  └─ Can revoke access anytime
  └─ App stores refresh token securely

​
Troubleshooting

ProblemSolution
API key rejectedKey may be expired. Check creation date. Regenerate if old.
Session expiredAutomatic. Log in again. Browser will remember.
JWT invalidToken may be expired. Request new token. Check timestamp.
401 UnauthorizedCheck auth header format. Verify credentials. Check IP allowlist.
Next: Explore API Keys for server-to-server authentication.