Authentication

Learn how to authenticate with the Deepns API.

API Keys

Deepns uses API keys to authenticate API requests. Your API keys carry privileges, so keep them secure and never share them publicly.

Getting Your API Key

  1. Log in to your Deepns dashboard
  2. Navigate to Settings > API Keys
  3. Click “Generate New Key”
  4. Name your key (e.g., “Production Server”)
  5. Copy and save the key securely

⚠️ Important: API keys are only shown once during creation. Store them securely.

Authentication Methods

Bearer Token

Include your API key in the Authorization header:

curl https://api.deepns.com/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

For testing only, you can pass the key as a query parameter:

curl https://api.deepns.com/events?api_key=YOUR_API_KEY

⚠️ Warning: Avoid using query parameters in production as they may be logged.

API Key Types

Public Keys

  • Used for client-side tracking
  • Limited to creating events
  • Safe to embed in JavaScript
  • Format: pk_live_... or pk_test_...

Example:

deepns.init('pk_live_abc123');

Secret Keys

  • Used for server-side operations
  • Full API access
  • Must be kept secret
  • Format: sk_live_... or sk_test_...

Example:

curl https://api.deepns.com/analytics \
  -H "Authorization: Bearer sk_live_xyz789"

Environments

Use different keys for different environments:

Environment Key Prefix Usage
Test pk_test_, sk_test_ Development and testing
Live pk_live_, sk_live_ Production

Key Management

Rotating Keys

Rotate keys regularly:

  1. Generate new API key
  2. Update applications with new key
  3. Test thoroughly
  4. Revoke old key

Revoking Keys

Immediately revoke compromised keys:

  1. Go to Settings > API Keys
  2. Find the compromised key
  3. Click “Revoke”
  4. Generate a replacement key

Security Best Practices

Do’s

✅ Store keys in environment variables
✅ Use different keys for each environment
✅ Rotate keys periodically
✅ Monitor API key usage
✅ Use public keys for client-side code

Don’ts

❌ Commit keys to version control
❌ Share keys in public channels
❌ Use production keys in development
❌ Hard-code keys in source code
❌ Use secret keys in client-side code

Example: Environment Variables

Node.js

require('dotenv').config();

const apiKey = process.env.DEEPNS_API_KEY;

fetch('https://api.deepns.com/events', {
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  }
});

Ruby on Rails

# config/credentials.yml.enc
deepns:
  api_key: sk_live_xyz789

# In your code
api_key = Rails.application.credentials.deepns[:api_key]

Python

import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('DEEPNS_API_KEY')

headers = {
    'Authorization': f'Bearer {api_key}',
    'Content-Type': 'application/json'
}

Error Responses

401 Unauthorized

Missing or invalid API key:

{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Solution: Check your API key is correct and included in the request.

403 Forbidden

API key doesn’t have required permissions:

{
  "error": "forbidden",
  "message": "API key does not have permission for this resource"
}

Solution: Use a secret key or ensure the key has correct permissions.

Testing Authentication

Test your API key:

curl https://api.deepns.com/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

Successful response:

{
  "valid": true,
  "key_type": "secret",
  "environment": "live",
  "permissions": ["read", "write"]
}

Next Steps

Documentation