Skip to main content

Authentication

Saddle Data supports two primary methods of authentication: Session Authentication (for UI users) and API Key Authentication (for programmatic access and IaC).

Session Authentication (JWT)​

When you log in to the Saddle Data dashboard, your browser uses a Firebase ID Token (JWT). This is the default method for all interactive operations.

  • Header: Authorization: Bearer <ID_TOKEN>
  • Expiry: Typically 1 hour.
  • Use Case: Interactive CLI usage or local debugging while logged in.

API Key Authentication​

For automation, CI/CD pipelines, and Infrastructure as Code (IaC), you should use API Keys. API Keys are scoped to an organization and can be assigned specific roles.

Generating an API Key​

  1. Navigate to Organization Settings.
  2. Click on the "API Keys" tab.
  3. Click "Generate New Key".
  4. Provide a descriptive name (e.g., "Terraform CI").
  5. Select the appropriate Roles (Admin, Editor, or Viewer).
  6. Copy the key immediately. For security, the plain-text key is only shown once and cannot be retrieved later.

Using an API Key​

Include your API key in the X-Api-Key header of your requests:

curl -H "X-Api-Key: sd_your_api_key_here" https://api.saddledata.io/v1/organizations/:orgId/flows

Roles and Permissions​

API Keys honor the same Role-Based Access Control (RBAC) system as users:

  • Admin: Full access to all resources, including member management and billing.
  • Editor: Can create, update, and delete flows, connections, and integrations.
  • Viewer: Read-only access to all resources.

Idempotency​

For state-changing requests (POST, PUT, PATCH, DELETE), you can include an X-Idempotency-Key header. This ensures that retrying a request (e.g., due to a network timeout) will return the cached response rather than creating duplicate resources.

X-Idempotency-Key: <unique_client_generated_uuid>