API Access

FWURL's API allows you to programmatically create links, retrieve analytics, and manage your account. This guide covers how to generate, manage, and secure your API tokens.

Accessing API Settings

1. Click your profile avatar in the top-right corner
2. Select Settings from the dropdown menu
3. Click the API tab

Understanding API Tokens

What is an API Token?

An API token is a unique credential that allows external applications to access your FWURL account. It acts as a password for programmatic access.

Use cases:

• Automating link creation
• Integrating with other tools
• Building custom dashboards
• Bulk operations via scripts

Token Security

API tokens provide full access to your account. Treat them like passwords:

• Never share tokens publicly
• Don't commit tokens to version control
• Use environment variables in code
• Rotate tokens periodically
• Revoke compromised tokens immediately

Managing Your API Token

Generating a New Token

If you don't have an API token:

1. Go to Settings → API
2. Click Create API Token
3. Confirm the action
4. Copy your token immediately

Important: The full token is only shown once. Copy and store it securely before closing the dialog.

Viewing Your Token

After creation, the API tab shows:

• A masked version of your token (e.g., fwurl_••••••••••••••••)
• Token creation date
• Last used timestamp (if available)

You cannot view the full token again after initial creation. If you lose it, you'll need to regenerate.

Copying Your Token

When the token is first created:

1. Click Copy or the copy icon
2. A confirmation message appears
3. Paste into your secure storage immediately

Regenerating Your Token

To replace your existing token with a new one:

1. Go to Settings → API
2. Click Regenerate Token
3. Read the warning carefully
4. Confirm the action
5. Copy your new token immediately

Warning: Regenerating invalidates your previous token immediately. All applications using the old token will stop working.

When to regenerate:

• Token may have been exposed
• Regular security rotation (recommended every 90 days)
• Team member with access leaves
• Suspicious API activity detected

Revoking Your Token

To completely disable API access:

1. Go to Settings → API
2. Click Revoke Token
3. Confirm the action
4. Token is immediately invalidated

After revocation, you can create a new token when needed.

Using Your API Token

Authentication

Include your token in the Authorization header:

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

Basic API Request

Create a short link:

curl -X POST https://api.fwurl.com/v1/links \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/my-long-url",
    "alias": "my-link"
  }'

Response Format

Successful responses return JSON:

{
  "success": true,
  "data": {
    "id": "abc123",
    "short_url": "https://fwurl.com/my-link",
    "original_url": "https://example.com/my-long-url",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Error responses include error details:

{
  "success": false,
  "error": {
    "code": "INVALID_URL",
    "message": "The provided URL is not valid"
  }
}

Rate Limits

API requests are rate-limited based on your plan:

Rate Limit Headers

Each response includes rate limit information:

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9847
X-RateLimit-Reset: 1705334400

Handling Rate Limits

When you hit the limit, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 60
  }
}

Best practices:

• Implement exponential backoff
• Cache responses when possible
• Batch operations where supported
• Monitor your usage proactively

API Security Best Practices

Environment Variables

Never hardcode tokens in your code:

# Good - using environment variable
export FWURL_API_TOKEN="your_token_here"

// In your code
const token = process.env.FWURL_API_TOKEN;

Secrets Management

For production applications:

• Use a secrets manager (AWS Secrets Manager, HashiCorp Vault)
• Encrypt tokens at rest
• Limit access to secrets
• Audit secret access

Version Control

Prevent accidental commits:

# .gitignore
.env
.env.local
*.env
config/secrets.yml

Use pre-commit hooks to detect exposed tokens.

Token Rotation

Establish a rotation schedule:

1. Generate new token
2. Update all applications
3. Verify applications work
4. Revoke old token

Recommended rotation: Every 90 days

Troubleshooting

"Unauthorized" Error

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API token"
  }
}

Solutions:

• Verify token is correct
• Check Authorization header format: Bearer YOUR_TOKEN
• Ensure token hasn't been revoked
• Regenerate token if needed

"Rate Limited" Error

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded"
  }
}

Solutions:

• Wait for the reset period
• Implement request throttling
• Upgrade your plan for higher limits
• Optimize your API usage

"Forbidden" Error

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This action is not allowed"
  }
}

Solutions:

• Verify your plan includes the feature
• Check you're accessing your own resources
• Review API documentation for endpoint permissions

API Documentation

For complete API documentation:

• API Reference - Full endpoint documentation
• API Quickstart - Get started in minutes
• API Examples - Common use cases

Webhooks (Coming Soon)

FWURL webhooks will notify your applications of events:

• Link created
• Link clicked (threshold)
• Link expired
• Usage limits reached

Stay tuned for webhook support in a future update.

Next Steps

API questions? Contact support or check our API documentation.