Authentication

Overview

The Observability API uses a DSN-based authentication system. Your DSN contains all the information needed to authenticate requests.

DSN Format

Your Data Source Name (DSN) is a URL that contains:

https://{publicKey}@api.transactional.dev/observability/{projectId}

Example:

https://pk_abc123xyz789@api.transactional.dev/observability/42

Getting Your DSN

1. Navigate to Observability in your dashboard
2. Select your project
3. Go to the Settings tab
4. Copy the DSN from the "Data Source Name" section

Authentication Methods

SDK (Recommended)

The SDK handles authentication automatically:

import { initObservability } from '@transactional/observability';
 
initObservability({
  dsn: process.env.TRANSACTIONAL_OBSERVABILITY_DSN!,
});

REST API

For direct API calls, include your public key as a Bearer token:

curl -X POST https://api.transactional.dev/observability/traces \
  -H "Authorization: Bearer pk_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": 42,
    "name": "my-trace",
    "startTime": "2024-01-01T00:00:00.000Z"
  }'

Sentry-Compatible Header

For compatibility with Sentry SDKs, you can also use the X-Sentry-Auth header:

curl -X POST https://api.transactional.dev/observability/store \
  -H "X-Sentry-Auth: Sentry sentry_key=pk_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Environment Variables

We recommend storing your DSN in an environment variable:

# .env
TRANSACTIONAL_OBSERVABILITY_DSN=https://pk_abc123xyz789@api.transactional.dev/observability/42

Framework-Specific Setup

Next.js

# .env.local
TRANSACTIONAL_OBSERVABILITY_DSN=your-dsn-here

Vercel

vercel env add TRANSACTIONAL_OBSERVABILITY_DSN

Docker

# docker-compose.yml
services:
  app:
    environment:
      - TRANSACTIONAL_OBSERVABILITY_DSN=${TRANSACTIONAL_OBSERVABILITY_DSN}

Security Considerations

Public vs Secret Keys

• Public Key (pk_...) - Safe to use in server-side code. Used for write operations (creating traces).
• Secret Key (coming soon) - For read operations and sensitive actions.

Best Practices

1. Never commit DSNs - Always use environment variables
2. Server-side only - Don't expose your DSN in client-side code
3. Rotate if compromised - Regenerate keys from the dashboard if exposed

Regenerating Keys

If your keys are compromised:

1. Go to your project settings
2. Click Regenerate Keys
3. Update your DSN in all applications
4. Deploy the updated configuration

Warning: Regenerating keys immediately invalidates the old DSN. Any applications using the old DSN will stop working.

Rate Limits

If you exceed rate limits, you'll receive a 429 Too Many Requests response.

Error Responses

Example error response:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

Next Steps

• Traces API
• TypeScript SDK
• Quickstart Guide