Authentication

HatiData supports three authentication methods, each suited to different access patterns. All authentication is enforced at the control plane middleware layer before any request reaches business logic.

Authentication Methods at a Glance

Method	Use Case	Header	Token Format
JWT	Dashboard users, SSO sessions	Authorization: Bearer <token>	RS256-signed JWT
API Key	Programmatic access, CI/CD, agents	X-API-Key: hd_live_...	hd_live_ / hd_test_ prefix
Federated	Cloud-native workloads	Authorization: Bearer <token>	Cloud provider token

JWT Authentication

JSON Web Tokens are used for dashboard access and SSO-authenticated sessions.

Token Structure

{
  "sub": "usr_a1b2c3d4",
  "org_id": "org_x9y8z7w6",
  "role": "admin",
  "env": "production",
  "iat": 1708000000,
  "exp": 1708003600,
  "iss": "https://api.hatidata.com"
}

Token Lifecycle

Stage	Duration	Notes
Access token	1 hour	Short-lived, included in every request
Refresh token	7 days	Used to obtain new access tokens
Session maximum	30 days	Forces re-authentication

Refresh Flow

Client                    Control Plane
  │                            │
  ├─ POST /v1/auth/refresh ──►│
  │  { refresh_token: "..." } │
  │                            │
  │◄── 200 ───────────────────┤
  │  { access_token: "...",   │
  │    refresh_token: "...",  │
  │    expires_in: 3600 }     │

Token Storage

Never store JWTs in localStorage in browser applications. The HatiData dashboard uses httpOnly cookies with SameSite=Strict and Secure flags.

API Keys

API keys are the primary authentication method for programmatic access, SDK usage, and AI agent connections.

Key Format

hd_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6   # Production
hd_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6   # Staging/Test

• Prefix: hd_live_ for production environments, hd_test_ for staging/test
• Body: 32 cryptographically random alphanumeric characters
• Storage: Hashed with Argon2id (per-key salt) before storage. The plaintext key is displayed exactly once at creation time.

Scopes

Each API key is assigned one or more scopes that control what operations it can perform. HatiData defines 22 granular scope variants organized into bundles:

{
  "key_name": "analytics-agent",
  "scopes": ["query:read", "schema:read"],
  "environments": ["production"],
  "ip_allowlist": ["10.0.0.0/8"]
}

Scope Bundles:

Bundle	Scopes	Use Case
read_only	query:read, schema:read, audit:read	BI tools, dashboards
developer	ReadOnly + query:write, schema:write, environment:read	Development workflows
admin	Developer + policy:*, user:*, key:*, webhook:*, billing:read	Organization administrators
agent	query:read, query:write, schema:read, agent:*	AI agents

IP Allowlisting

Keys can be restricted to specific IP addresses or CIDR ranges:

{
  "ip_allowlist": [
    "10.0.0.0/8",
    "172.16.0.0/12",
    "192.168.1.100/32"
  ]
}

Requests from non-allowed IPs receive a 403 Forbidden response, and the attempt is logged in the IAM audit trail.

Key Rotation

API keys support automatic rotation with a configurable grace period:

1. Call POST /v1/environments/{env_id}/api-keys/{key_id}/rotate
2. A new key is generated and returned
3. Both old and new keys are valid during the 72-hour grace period
4. After the grace period, the old key is revoked
5. Expiration alerts are sent via configured webhooks

curl -X POST https://api.hatidata.com/v1/environments/env_abc/api-keys/key_123/rotate \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json"

{
  "key_id": "key_123",
  "new_key": "hd_live_n3w5ecr3tk3y...",
  "old_key_expires_at": "2026-02-19T00:00:00Z",
  "grace_period_hours": 72
}

Federated Authentication

HatiData supports cloud-native authentication through identity federation, allowing workloads to authenticate without managing API keys.

AWS STS Federation

import boto3
from hatidata_agent import HatiDataAgent

# Assume role and get credentials
sts = boto3.client("sts")
response = sts.assume_role_with_web_identity(
    RoleArn="arn:aws:iam::123456789012:role/HatiDataAgent",
    RoleSessionName="my-agent",
    WebIdentityToken=token,
)

agent = HatiDataAgent(
    host="your-org.proxy.hatidata.com",
    port=5439,
    auth_method="federated",
    federated_token=response["Credentials"]["SessionToken"],
)

GCP Workload Identity

from google.auth import default
from hatidata_agent import HatiDataAgent

credentials, project = default(
    scopes=["https://www.googleapis.com/auth/cloud-platform"]
)

agent = HatiDataAgent(
    host="your-org.proxy.hatidata.com",
    port=5439,
    auth_method="federated",
    federated_token=credentials.token,
)

Azure Managed Identity

from azure.identity import ManagedIdentityCredential
from hatidata_agent import HatiDataAgent

credential = ManagedIdentityCredential()
token = credential.get_token("https://hatidata.com/.default")

agent = HatiDataAgent(
    host="your-org.proxy.hatidata.com",
    port=5439,
    auth_method="federated",
    federated_token=token.token,
)

Token Caching

Federated tokens are cached in a DashMap with TTL-based expiration. Tokens are refreshed automatically when they approach expiration (within 5 minutes of expiry). This eliminates redundant round-trips to the identity provider.

SSO / WorkOS Integration

HatiData integrates with WorkOS for enterprise Single Sign-On:

Protocol	Providers
SAML 2.0	Okta, OneLogin, PingFederate, custom SAML IdPs
OIDC	Azure AD, Google Workspace, Auth0

SSO Configuration

SSO is configured at the organization level:

curl -X PUT https://api.hatidata.com/v1/organizations/org_abc/sso \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "okta",
    "domain": "yourcompany.okta.com",
    "client_id": "0oa...",
    "enforce_sso": true
  }'

When enforce_sso is true, all users in the organization must authenticate through the SSO provider. Password-based login is disabled.

MFA (Multi-Factor Authentication)

MFA can be enforced organization-wide:

curl -X PUT https://api.hatidata.com/v1/organizations/org_abc/settings \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_required": true,
    "mfa_methods": ["totp", "webauthn"]
  }'

Supported MFA methods:

Method	Description
TOTP	Time-based one-time passwords (Google Authenticator, Authy)
WebAuthn	Hardware security keys (YubiKey, Touch ID)

When MFA is enforced, users without a registered MFA method are prompted to enroll on their next login.

Authentication Middleware Pipeline

The control plane processes authentication in three middleware layers:

Request → Rate Limiter → Audit Logger → Auth Middleware → Handler
                                             │
                                   ┌─────────┼──────────┐
                                   │         │          │
                                  JWT    API Key   Federated
                                   │         │          │
                                   └─────────┼──────────┘
                                             │
                                        Session Context
                                    (user, org, role, scopes)

Failed authentication attempts are always logged with source IP, attempted method, and failure reason.

Next Steps

• Authorization -- RBAC roles and ABAC policies
• API Keys -- Key management API endpoints
• Security Overview -- Complete security architecture