Skip to main content

Authentication

LinkForty API uses API keys for authentication. All API requests must include a valid API key in the Authorization header.

Overview​

Base URL:

https://api.linkforty.com

Authentication Method: Bearer token (API key)

Header Format:

Authorization: Bearer YOUR_API_KEY_HERE

Getting Your API Key​

Via Dashboard​

  1. Log in to your LinkForty dashboard
  2. Navigate to Settings → API Keys
  3. Click "Create API Key"
  4. Enter a descriptive name (e.g., "Production Server", "CI/CD Pipeline")
  5. Click "Generate"
  6. Copy and save the key immediately - it won't be shown again

Via API (Using Existing Key)​

curl -X POST https://api.linkforty.com/api/settings/api-keys \
  -H "Authorization: Bearer $EXISTING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Production Key"
  }'

Response:

{
  "id": "key_abc123xyz",
  "name": "New Production Key",
  "key": "lf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "createdAt": "2024-01-15T10:30:00Z",
  "lastUsedAt": null
}

Important: Save the key value immediately. It cannot be retrieved later.

API Key Format​

LinkForty API keys follow this format:

lf_{environment}_{32_character_random_string}

Environments:

  • lf_live_ - Production keys (live data)
  • lf_test_ - Test keys (sandbox mode, not yet implemented)

Example:

lf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Making Authenticated Requests​

cURL​

curl -X GET https://api.linkforty.com/api/links \
  -H "Authorization: Bearer lf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

JavaScript (fetch)​

const API_KEY = 'lf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';

const response = await fetch('https://api.linkforty.com/api/links', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const links = await response.json();

Node.js (axios)​

const axios = require('axios');

const api = axios.create({
  baseURL: 'https://api.linkforty.com',
  headers: {
    'Authorization': `Bearer ${process.env.LINKFORTY_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

// Get all links
const { data: links } = await api.get('/api/links');

// Create a link
const { data: newLink } = await api.post('/api/links', {
  templateId: 'template_123',
  originalUrl: 'https://example.com/product'
});

Python (requests)​

import requests
import os

API_KEY = os.environ.get('LINKFORTY_API_KEY')
BASE_URL = 'https://api.linkforty.com'

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

# Get all links
response = requests.get(f'{BASE_URL}/api/links', headers=headers)
links = response.json()

# Create a link
response = requests.post(
    f'{BASE_URL}/api/links',
    headers=headers,
    json={
        'templateId': 'template_123',
        'originalUrl': 'https://example.com/product'
    }
)
new_link = response.json()

Go​

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

const baseURL = "https://api.linkforty.com"

func main() {
    apiKey := os.Getenv("LINKFORTY_API_KEY")

    client := &http.Client{}

    // Get all links
    req, _ := http.NewRequest("GET", baseURL+"/api/links", nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)

    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var links []map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&links)
    fmt.Println(links)
}

Ruby​

require 'net/http'
require 'json'

API_KEY = ENV['LINKFORTY_API_KEY']
BASE_URL = 'https://api.linkforty.com'

# Get all links
uri = URI("#{BASE_URL}/api/links")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{API_KEY}"
request['Content-Type'] = 'application/json'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

links = JSON.parse(response.body)
puts links

Security Best Practices​

1. Never Hardcode API Keys​

❌ Bad:

const API_KEY = 'lf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6';

✅ Good:

const API_KEY = process.env.LINKFORTY_API_KEY;

2. Use Environment Variables​

.env file:

LINKFORTY_API_KEY=lf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Load in your app:

// Node.js (with dotenv)
require('dotenv').config();
const API_KEY = process.env.LINKFORTY_API_KEY;

// Python (with python-dotenv)
from dotenv import load_dotenv
import os
load_dotenv()
API_KEY = os.environ.get('LINKFORTY_API_KEY')

Add to .gitignore:

.env
.env.local

3. Use Separate Keys for Different Environments​

Create different API keys for:

  • Production server
  • Staging server
  • Development/local
  • CI/CD pipelines
  • Each team member

Example naming:

Production API Key
Staging API Key
John's Development Key
GitHub Actions CI

4. Rotate Keys Regularly​

Best practice: Rotate API keys every 90 days.

Steps:

  1. Create new API key
  2. Update environment variables in all systems
  3. Test new key works
  4. Delete old key

5. Restrict Key Permissions (Coming Soon)​

Future feature: Scope keys to specific actions.

{
  "name": "Read-Only Analytics Key",
  "permissions": ["analytics:read"],
  "rateLimit": 100
}

6. Monitor Key Usage​

Check when keys were last used:

Via Dashboard:

  1. Settings → API Keys
  2. View "Last Used" column
  3. Delete unused keys

Via API:

curl -X GET https://api.linkforty.com/api/settings/api-keys \
  -H "Authorization: Bearer $LINKFORTY_API_KEY"

Response:

{
  "apiKeys": [
    {
      "id": "key_abc123",
      "name": "Production API Key",
      "keyPrefix": "lf_live_a1b2****",
      "createdAt": "2024-01-15T10:30:00Z",
      "lastUsedAt": "2024-01-20T14:25:00Z"
    },
    {
      "id": "key_def456",
      "name": "Old Unused Key",
      "keyPrefix": "lf_live_x9y8****",
      "createdAt": "2023-06-01T08:00:00Z",
      "lastUsedAt": "2023-12-15T09:00:00Z"
    }
  ]
}

Action: Delete key_def456 if no longer needed.

Error Responses​

Missing API Key​

Request:

curl -X GET https://api.linkforty.com/api/links
# No Authorization header

Response: 401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Missing or invalid API key",
  "statusCode": 401
}

Invalid API Key​

Request:

curl -X GET https://api.linkforty.com/api/links \
  -H "Authorization: Bearer invalid_key_12345"

Response: 401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid API key",
  "statusCode": 401
}

Expired/Deleted API Key​

Request:

curl -X GET https://api.linkforty.com/api/links \
  -H "Authorization: Bearer lf_live_deleted_key_abc123"

Response: 401 Unauthorized

{
  "error": "Unauthorized",
  "message": "API key has been deleted or revoked",
  "statusCode": 401
}

Wrong Organization​

Request: Attempting to access resources from a different organization

Response: 403 Forbidden

{
  "error": "Forbidden",
  "message": "You do not have access to this resource",
  "statusCode": 403
}

Managing API Keys​

List All API Keys​

curl -X GET https://api.linkforty.com/api/settings/api-keys \
  -H "Authorization: Bearer $LINKFORTY_API_KEY"

Response:

{
  "apiKeys": [
    {
      "id": "key_abc123",
      "name": "Production API Key",
      "keyPrefix": "lf_live_a1b2****",
      "createdAt": "2024-01-15T10:30:00Z",
      "lastUsedAt": "2024-01-20T14:25:00Z"
    },
    {
      "id": "key_def456",
      "name": "Staging API Key",
      "keyPrefix": "lf_live_c3d4****",
      "createdAt": "2024-01-10T09:00:00Z",
      "lastUsedAt": "2024-01-19T16:30:00Z"
    }
  ]
}

Note: Full key values are never returned. Only first 8 characters shown.

Create New API Key​

curl -X POST https://api.linkforty.com/api/settings/api-keys \
  -H "Authorization: Bearer $LINKFORTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline"
  }'

Response:

{
  "id": "key_ghi789",
  "name": "CI/CD Pipeline",
  "key": "lf_live_e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
  "createdAt": "2024-01-20T10:00:00Z",
  "lastUsedAt": null
}

⚠️ Important: Save the key value now. It cannot be retrieved later.

Delete API Key​

curl -X DELETE https://api.linkforty.com/api/settings/api-keys/key_abc123 \
  -H "Authorization: Bearer $LINKFORTY_API_KEY"

Response: 204 No Content

Note: Deletion is immediate. All requests using this key will fail instantly.

Update API Key Name​

curl -X PUT https://api.linkforty.com/api/settings/api-keys/key_abc123 \
  -H "Authorization: Bearer $LINKFORTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key (Updated)"
  }'

Response:

{
  "id": "key_abc123",
  "name": "Production API Key (Updated)",
  "keyPrefix": "lf_live_a1b2****",
  "createdAt": "2024-01-15T10:30:00Z",
  "lastUsedAt": "2024-01-20T14:25:00Z"
}

Testing Your API Key​

Quick Health Check​

curl -X GET https://api.linkforty.com/api/health \
  -H "Authorization: Bearer $LINKFORTY_API_KEY"

Response: 200 OK

{
  "status": "ok",
  "timestamp": "2024-01-20T15:30:00Z",
  "user": {
    "id": "user_abc123",
    "email": "developer@example.com",
    "organizationId": "org_def456"
  }
}

Verify Permissions​

curl -X GET https://api.linkforty.com/api/auth/me \
  -H "Authorization: Bearer $LINKFORTY_API_KEY"

Response: 200 OK

{
  "id": "user_abc123",
  "email": "developer@example.com",
  "organizationId": "org_def456",
  "role": "owner"
}

Rate Limiting​

See Rate Limits for details on API rate limiting.

Summary:

  • Default: 100 requests/minute per API key
  • Burst: 200 requests/minute (short bursts allowed)
  • Contact us for higher limits

SDK Support​

Official SDKs​

JavaScript/TypeScript:

npm install @linkforty/sdk
import { LinkFortySDK } from '@linkforty/sdk';

const client = new LinkFortySDK({
  apiKey: process.env.LINKFORTY_API_KEY
});

const links = await client.links.list();
const newLink = await client.links.create({
  templateId: 'template_123',
  originalUrl: 'https://example.com'
});

Python:

pip install linkforty
from linkforty import LinkForty

client = LinkForty(api_key=os.environ['LINKFORTY_API_KEY'])

links = client.links.list()
new_link = client.links.create(
    template_id='template_123',
    original_url='https://example.com'
)

Troubleshooting​

"Missing or invalid API key"​

Cause: Authorization header not included or malformed.

Solutions:

  1. Verify header format: Authorization: Bearer YOUR_API_KEY
  2. Check for typos in "Authorization" or "Bearer"
  3. Ensure API key is complete (starts with lf_live_)

"API key has been deleted or revoked"​

Cause: The API key was deleted from the dashboard.

Solution:

  1. Create new API key in dashboard
  2. Update environment variables
  3. Restart application

"You do not have access to this resource"​

Cause: API key belongs to different organization than resource.

Solution:

  1. Verify you're using correct API key
  2. Check resource ID belongs to your organization
  3. Ensure you have proper role (Owner/Admin)

Requests Work Locally But Fail in Production​

Cause: Environment variable not set in production.

Solution:

  1. Verify LINKFORTY_API_KEY is set in production environment
  2. Check deployment platform docs (Vercel, Heroku, AWS, etc.)
  3. Test with: echo $LINKFORTY_API_KEY (should output key)

Next Steps​