Authentication

The Nudg3 API uses API keys to authenticate requests. All API requests must include a valid API key in the request headers.

API Key Format

Nudg3 API keys follow a specific format:

nudg3_[env]_ak_[key_id]_[random_chars]

Example Key

nudg3_live_ak_a1b2c3d4_xYz9AbCdEf...

Using Your API Key

Include your API key in the Authorization header using the Bearer scheme:

curl https://api.nudg3.ai/api/v1/dashboard \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Alternatively, you can use the X-API-Key header:

curl https://api.nudg3.ai/api/v1/dashboard \
  -H "X-API-Key: nudg3_live_ak_your_key"

Creating API Keys

1. Log in to your Nudg3 Dashboard
2. Go to Settings > API Keys
3. Click Create New Key
4. Configure your key:
   • Name: A descriptive name for the key
   • Scopes: Permissions for the key (see below)
   • IP Allowlist (optional): Restrict key usage to specific IPs
5. Click Create and copy your key

Scopes and Tiers

API keys have scoped permissions organized into two tiers:

API Tiers

Available Scopes

Checking Key Scopes

The API returns your key's scopes in the rate limit response headers:

X-API-Scopes: read:analytics,export:data
X-API-Tier: premium

Security Best Practices

Environment Variables

Store API keys in environment variables, not in code:

# .env file
NUDG3_API_KEY=nudg3_live_ak_your_key

// Access in code
const apiKey = process.env.NUDG3_API_KEY;

Key Rotation

Regularly rotate your API keys:

1. Create a new key with the same scopes
2. Update your applications to use the new key
3. Verify everything works
4. Revoke the old key

IP Allowlisting

For production keys, restrict usage to known IP addresses:

1. Go to Settings > API Keys
2. Edit your key
3. Add allowed IP addresses or CIDR ranges
4. Save changes

Never Expose Keys

• Don't commit keys to version control
• Don't include keys in client-side JavaScript
• Don't share keys in public forums or documentation
• Do use environment variables
• Do use server-side code to make API calls

Revoking Keys

If a key is compromised:

1. Go to Settings > API Keys
2. Find the compromised key
3. Click Revoke
4. Create a new key
5. Update your applications

Error Responses

Authentication errors return specific error codes:

Example error response:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid",
    "hint": "Check that you're using the correct key format"
  }
}

Next Steps