Skip to content
Documentation

Authentication & Authorization

Authentication & Authorization

Section titled “Authentication & Authorization”

Querri uses a multi-layered approach to authentication and authorization to ensure secure access to data and resources.

Authentication Flow

Section titled “Authentication Flow”

WorkOS SSO Integration

Section titled “WorkOS SSO Integration”

Querri uses WorkOS for enterprise-grade Single Sign-On (SSO):

  1. User initiates login at frontend
  2. Frontend redirects to WorkOS authentication page
  3. User authenticates with their organization’s identity provider
  4. WorkOS validates credentials and returns auth code
  5. Hub service exchanges code for user profile
  6. JWT token issued with user claims
  7. Frontend stores token for API requests

JWT Token Structure

Section titled “JWT Token Structure”
{
  "user_id": "usr_123456",
  "email": "user@example.com",
  "organization_id": "org_789",
  "workos_id": "user_workos_abc",
  "exp": 1234567890,
  "iat": 1234567890
}

Token Lifecycle

Section titled “Token Lifecycle”
  • Issued: On successful login
  • Expiration: 7 days default
  • Refresh: Automatic renewal before expiration
  • Revocation: On logout or security events

Authorization

Section titled “Authorization”

Fine-Grained Authorization (FGA)

Section titled “Fine-Grained Authorization (FGA)”

Querri implements FGA for resource-level permissions:

Permission Model

Section titled “Permission Model”
user:user_123
  ├─ can view → project:proj_456
  ├─ can edit → project:proj_789
  └─ can admin → organization:org_001


organization:org_001
  └─ members can view → connector:conn_123

Resource Types

Section titled “Resource Types”
  • Projects: View, edit, delete, share
  • Dashboards: View, edit, embed
  • Files: View, download, delete
  • Connectors: Use, edit, delete
  • Organizations: Admin, member

Permission Levels

Section titled “Permission Levels”

  1. Viewer: Read-only access

    • View project results
    • View dashboards
    • Download data

  2. Editor: Modify resources

    • Create/edit projects
    • Create/edit dashboards
    • Upload files

  3. Admin: Full control

    • Manage sharing
    • Delete resources
    • Manage connectors
    • Invite users

Organization-Level Permissions

Section titled “Organization-Level Permissions”

All users in an organization have:

  • Access to organization connectors
  • Ability to create projects
  • View organization members
  • Access to shared resources

Public Sharing

Section titled “Public Sharing”

Projects and dashboards can be shared publicly:

Section titled “Share Links”
  • Time-limited: Expire after set duration
  • Token-based: Unique URL with access token
  • Anonymous: No login required
  • Read-only: View-only access
Section titled “Share Link Format”
https://app.querri.com/share/{token}/project/{uuid}

API Authentication

Section titled “API Authentication”

All API requests require authentication:

Header Format

Section titled “Header Format”
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Traefik JWT Validation

Section titled “Traefik JWT Validation”

Traefik validates JWT before routing:

  1. Extract JWT from Authorization header
  2. Verify signature using secret key
  3. Check expiration timestamp
  4. Allow request if valid, reject if invalid
  5. Add user context to request headers

Session Management

Section titled “Session Management”

Frontend Session

Section titled “Frontend Session”
  • Token storage: Memory (recommended) or localStorage
  • Auto-refresh: Before token expiration
  • Logout: Clear token and redirect to login

Backend Session

Section titled “Backend Session”
  • Redis-based: Session data stored in Redis
  • TTL: Matches JWT expiration
  • Cleanup: Automatic expiration via Redis TTL

Security Features

Section titled “Security Features”

Password Requirements

Section titled “Password Requirements”

WorkOS handles password requirements based on organization policy:

  • Minimum length
  • Complexity rules
  • Expiration policies
  • MFA requirements

Multi-Factor Authentication (MFA)

Section titled “Multi-Factor Authentication (MFA)”

Organizations can require MFA:

  • TOTP: Time-based one-time passwords
  • SMS: Text message codes
  • Push notifications: Mobile app approval

Account Security

Section titled “Account Security”
  • Session termination: Force logout on all devices
  • Activity logs: Audit trail of user actions
  • IP restrictions: Limit access by IP address
  • Device management: Track and manage authenticated devices

CORS Configuration

Section titled “CORS Configuration”

Allowed Origins

Section titled “Allowed Origins”

Development:

http://localhost:5173
http://localhost:3000

Production:

https://app.querri.com
https://*.querri.com

Allowed Methods

Section titled “Allowed Methods”
GET, POST, PUT, PATCH, DELETE, OPTIONS

Allowed Headers

Section titled “Allowed Headers”
Authorization
Content-Type
X-Requested-With

API Rate Limiting

Section titled “API Rate Limiting”

Rate limits prevent abuse:

  • Authenticated users: 1000 requests/hour
  • Public shares: 100 requests/hour
  • File uploads: 10 GB/day per user

Rate Limit Headers

Section titled “Rate Limit Headers”
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1234567890

Security Best Practices

Section titled “Security Best Practices”

For Administrators

Section titled “For Administrators”
  1. Enable MFA for all users
  2. Review permissions regularly
  3. Audit share links and revoke unused ones
  4. Monitor activity logs for suspicious behavior
  5. Rotate API keys periodically

For Developers

Section titled “For Developers”
  1. Never log JWTs or credentials
  2. Use HTTPS for all requests
  3. Validate input on both client and server
  4. Implement CSRF protection for state-changing operations
  5. Follow principle of least privilege

For End Users

Section titled “For End Users”
  1. Use strong passwords
  2. Enable MFA if available
  3. Don’t share credentials
  4. Review active sessions regularly
  5. Report suspicious activity

Troubleshooting

Section titled “Troubleshooting”

”Unauthorized” Errors

Section titled “”Unauthorized” Errors”

Check:

  1. JWT token is present in request
  2. Token hasn’t expired
  3. User has required permissions
  4. Token signature is valid

”Forbidden” Errors

Section titled “”Forbidden” Errors”

Check:

  1. User has permission for the resource
  2. Resource belongs to user’s organization
  3. Share link hasn’t expired

Session Expires Quickly

Section titled “Session Expires Quickly”

Possible causes:

  1. System time is incorrect
  2. Redis session expired early
  3. Organization policy requires shorter sessions

Next Steps

Section titled “Next Steps”