FWURL/Docs

API Authentication

The FWURL API uses API key authentication. This guide covers how to obtain, use, and manage your API keys.

API Key Types

FWURL offers two types of API keys:

Read-Only Keys

  • View links and analytics
  • List domains and campaigns
  • Access account information
  • Cannot create, update, or delete resources

Full Access Keys

  • All read permissions
  • Create, update, and delete links
  • Manage domains and campaigns
  • Full account management
Best Practice

Use read-only keys when you only need to retrieve data. This minimizes security risks if a key is compromised.

Creating an API Key

Step 1: Navigate to API Settings

  1. Log in to your FWURL dashboard
  2. Click on your profile in the top right
  3. Select Settings from the dropdown
  4. Navigate to the API tab

Step 2: Generate a New Key

  1. Click Create API Key
  2. Enter a descriptive name (e.g., "Production Server", "Analytics Dashboard")
  3. Select the key type (Read-Only or Full Access)
  4. Click Generate

Step 3: Store Your Key Securely

Important

Your API key will be displayed only once. Make sure to:

  • Copy it immediately
  • Store it in a secure location (e.g., password manager, environment variable)
  • Never commit it to version control
  • Never share it publicly

Using Your API Key

Include your API key in the Authorization header of each request:

curl https://api.fwurl.com/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY"

Example: JavaScript

const response = await fetch('https://api.fwurl.com/v1/links', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

Example: Python

import requests
 
headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
response = requests.get('https://api.fwurl.com/v1/links', headers=headers)

Example: cURL

curl -X GET https://api.fwurl.com/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Authentication Errors

Invalid API Key

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked"
  }
}

HTTP Status: 401 Unauthorized

Missing API Key

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Include it in the Authorization header"
  }
}

HTTP Status: 401 Unauthorized

Insufficient Permissions

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Your API key does not have permission to perform this action"
  }
}

HTTP Status: 403 Forbidden

Security Best Practices

Environment Variables

Store your API keys in environment variables:

# .env
FWURL_API_KEY=your_api_key_here

Then access them in your code:

const apiKey = process.env.FWURL_API_KEY;

Key Rotation

Regularly rotate your API keys:

  1. Generate a new API key
  2. Update your applications to use the new key
  3. Revoke the old key

Monitoring

Monitor your API key usage in the dashboard:

  • View recent requests
  • Track failed authentication attempts
  • Set up alerts for suspicious activity

Revoking API Keys

If a key is compromised or no longer needed:

  1. Go to Settings > API
  2. Find the key in the list
  3. Click Revoke
  4. Confirm the action

Note: Revoking a key is immediate and cannot be undone. Make sure your applications are updated before revoking active keys.

Next Steps