Integration Tokens

Integration tokens provide programmatic access to the Datafi API without requiring interactive authentication through an identity provider. Use them for backend services, CI/CD pipelines, AI assistant integrations, and webhook consumers.

Token Types

Datafi supports two types of integration tokens, each designed for a different use case.

Token Type	Lifetime	Use Case	Permissions
API Token	Long-lived (configurable)	Backend services, scripts, scheduled jobs	Inherits the creating user's role or a custom role
Webhook Token	Long-lived (configurable)	Inbound webhooks from external systems	Scoped to specific webhook operations

Creating API Tokens

Via the Admin Console

1. Navigate to Settings > Integration Tokens.
2. Click Create Token.
3. Configure the token:

Field	Required	Description
Name	Yes	A descriptive name for the token (e.g., "ETL Pipeline - Production")
Role	Yes	The RBAC role assigned to the token
Expiration	Yes	When the token expires (30 days, 90 days, 1 year, or custom)
Workspace scope	No	Restrict the token to a specific workspace
IP allowlist	No	Restrict token usage to specific IP ranges

4. Click Generate. The token is displayed once -- copy it immediately.

warning

The token value is shown only at creation time. If you lose it, you must revoke the token and create a new one. Datafi does not store the raw token value.

Via the API

curl -X POST https://api.datafi.io/v1/admin/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ETL Pipeline - Production",
    "role": "editor",
    "expires_in_days": 90,
    "workspace_id": "ws_analytics",
    "ip_allowlist": ["10.0.0.0/8"]
  }'

Response:

{
  "token_id": "tok_abc123",
  "name": "ETL Pipeline - Production",
  "token": "dfi_live_7f8a9b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a",
  "role": "editor",
  "workspace_id": "ws_analytics",
  "expires_at": "2025-04-15T00:00:00Z",
  "created_at": "2025-01-15T10:30:00Z",
  "created_by": "user_admin001"
}

Using API Tokens

Include the token as a Bearer token in the Authorization header, just like a JWT.

gRPC

metadata: {
  "authorization": "Bearer dfi_live_7f8a9b2c..."
}

HTTP

curl https://api.datafi.io/v1/query/execute \
  -H "Authorization: Bearer dfi_live_7f8a9b2c..." \
  -H "Content-Type: application/json" \
  -d '{"sql": "SELECT COUNT(*) FROM customers"}'

MCP

{
  "mcpServers": {
    "datafi": {
      "url": "https://api.datafi.io:8002",
      "headers": {
        "Authorization": "Bearer dfi_live_7f8a9b2c..."
      }
    }
  }
}

Token Prefixes

Datafi tokens use prefixes to help you identify token types and environments at a glance.

Prefix	Type	Environment
dfi_live_	API token	Production
dfi_test_	API token	Test / Staging
dfi_whk_	Webhook token	Any

Managing Tokens

List Tokens

curl https://api.datafi.io/v1/admin/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Response:

{
  "tokens": [
    {
      "token_id": "tok_abc123",
      "name": "ETL Pipeline - Production",
      "role": "editor",
      "expires_at": "2025-04-15T00:00:00Z",
      "last_used_at": "2025-01-15T09:00:00Z",
      "status": "active"
    },
    {
      "token_id": "tok_def456",
      "name": "BI Dashboard Sync",
      "role": "viewer",
      "expires_at": "2025-07-01T00:00:00Z",
      "last_used_at": null,
      "status": "active"
    }
  ]
}

Revoke a Token

curl -X DELETE https://api.datafi.io/v1/admin/tokens/tok_abc123 \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Revoked tokens are immediately invalidated. Any request using a revoked token receives a 401 Unauthorized response.

Rotate a Token

To rotate a token without downtime:

1. Create a new token with the same configuration.
2. Update your integration to use the new token.
3. Verify the integration works with the new token.
4. Revoke the old token.

# Step 1: Create replacement token
curl -X POST https://api.datafi.io/v1/admin/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ETL Pipeline - Production (rotated)",
    "role": "editor",
    "expires_in_days": 90,
    "workspace_id": "ws_analytics"
  }'

# Step 3: After verifying the new token works, revoke the old one
curl -X DELETE https://api.datafi.io/v1/admin/tokens/tok_abc123 \
  -H "Authorization: Bearer $ADMIN_TOKEN"

Webhook Integrations

Webhook tokens are used to authenticate inbound webhook requests from external systems. When an external system sends data to Datafi via a webhook, the request must include a valid webhook token.

Creating a Webhook Endpoint

curl -X POST https://api.datafi.io/v1/admin/webhooks \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Sync",
    "description": "Receives push events from GitHub",
    "events": ["push", "pull_request"],
    "target_connection": "conn_abc123",
    "secret": "your-webhook-secret"
  }'

Response:

{
  "webhook_id": "whk_abc123",
  "name": "GitHub Sync",
  "url": "https://api.datafi.io/v1/webhooks/whk_abc123",
  "token": "dfi_whk_9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
  "created_at": "2025-01-15T10:30:00Z"
}

Webhook Signature Verification

Datafi signs outbound webhook payloads using HMAC-SHA256. Verify the signature to ensure the payload was sent by Datafi and has not been tampered with.

# The signature is included in the X-Datafi-Signature header
X-Datafi-Signature: sha256=a1b2c3d4e5f6...

Verification example (Python):

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Token Security

Practice	Description
Store securely	Use a secrets manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
Rotate regularly	Rotate tokens every 90 days or sooner for high-privilege tokens
Scope narrowly	Assign the minimum role and workspace scope needed
Use IP allowlists	Restrict token usage to known IP ranges when possible
Monitor usage	Review last_used_at timestamps to identify unused tokens
Revoke promptly	Revoke tokens immediately when they are no longer needed

Audit Trail

All token operations are logged for auditing.

Event	Logged Fields
Token created	Token ID, name, role, creator, expiration
Token used	Token ID, request ID, IP address, timestamp
Token revoked	Token ID, revoker, timestamp
Token expired	Token ID, expiration timestamp

{
  "event": "token.used",
  "token_id": "tok_abc123",
  "request_id": "req_7f8a9b2c",
  "ip_address": "10.0.1.42",
  "timestamp": "2025-01-15T10:30:00Z",
  "user_agent": "datafi-python-sdk/1.2.0"
}

Best Practices

1. Never embed tokens in source code. Use environment variables or a secrets manager.
2. Create purpose-specific tokens. Each integration should have its own token so that revoking one does not affect others.
3. Set expiration dates. Avoid creating tokens that never expire. Use 90-day expirations and rotate before they lapse.
4. Review tokens quarterly. Audit all active tokens, revoke unused ones, and verify that assigned roles are still appropriate.
5. Use webhook signatures. Always verify HMAC signatures on incoming webhook payloads to prevent tampering.