Skip to main content

API Authentication

All API requests require authentication. Learn how to authenticate and secure your API access.

Authentication Methods​

API Key Authentication​

The primary method for API authentication:

curl https://api.tagd-ai.com/v1/tags \
  -H "Authorization: Bearer YOUR_API_KEY"

Or via header:

curl https://api.tagd-ai.com/v1/tags \
  -H "X-API-Key: YOUR_API_KEY"

When to Use​

MethodUse Case
Bearer TokenServer-to-server, scripts
X-API-KeyAlternative header format

API Keys​

Key Format​

API keys look like:

tagd_live_a1b2c3d4e5f6g7h8i9j0...

Prefixes:

  • tagd_live_ - Production keys
  • tagd_test_ - Sandbox/test keys

Key Properties​

Each key has:

  • Name - Descriptive label
  • Permissions - What it can access
  • Created date - When generated
  • Last used - Last API call
  • Enabled/Disabled - Active status

Creating API Keys​

From Dashboard​

  1. Go to Account → API Keys
  2. Click Create API Key
  3. Enter a name (e.g., "Production App")
  4. Select permissions
  5. Click Create
  6. Copy the key immediately - won't be shown again

Permissions​

Choose what the key can access:

PermissionDescription
tags:readRead tag content
tags:writeCreate/update tags
tags:deleteDelete tags
files:readDownload files
files:writeUpload files
webhooks:readList webhooks
webhooks:writeManage webhooks
analytics:readAccess analytics

Example: Read-Only Key​

For a key that only reads:

Permissions: tags:read, files:read

Example: Full Access Key​

For complete access:

Permissions: tags:read, tags:write, tags:delete,
             files:read, files:write,
             webhooks:read, webhooks:write,
             analytics:read

Key Security​

Best Practices​

  1. Never expose keys in client-side code

    • Keep keys on your server
    • Don't commit to version control
    • Use environment variables

  2. Use minimal permissions

    • Only grant needed permissions
    • Create separate keys for different uses
    • Read-only where possible

  3. Rotate keys regularly

    • Change keys periodically
    • Rotate after team member leaves
    • Regenerate if compromised

  4. Monitor usage

    • Check last used dates
    • Review API logs
    • Set up alerts

Environment Variables​

Store keys in environment:

# .env file (don't commit)
TAGD_API_KEY=tagd_live_abc123...

Use in code:

const apiKey = process.env.TAGD_API_KEY;

IP Restrictions​

Limit key usage to specific IPs:

  1. Go to API Keys → select key
  2. Click IP Restrictions
  3. Add allowed IPs:
    • Single IP: 192.168.1.1
    • CIDR range: 192.168.1.0/24
  4. Save

Requests from other IPs are rejected.

Key Management​

View All Keys​

  1. Go to Account → API Keys
  2. See list of all keys
  3. View:
    • Name
    • Permissions
    • Last used
    • Status

Disable a Key​

Temporarily stop a key:

  1. Find the key
  2. Toggle Enabled off
  3. Key stops working immediately
  4. Can re-enable later

Delete a Key​

Permanently remove:

  1. Find the key
  2. Click Delete
  3. Confirm deletion
  4. Key cannot be recovered

Regenerate a Key​

Get new key value:

  1. Find the key
  2. Click Regenerate
  3. New key value generated
  4. Old value stops working
  5. Copy new value immediately

Authentication Errors​

401 Unauthorized​

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

Causes:

  • Missing Authorization header
  • Invalid key
  • Disabled key
  • Deleted key

403 Forbidden​

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient permissions"
  }
}

Causes:

  • Key lacks required permission
  • Resource not accessible
  • IP not allowed

Rate Limiting​

Rate limits apply per API key:

PlanPer MinutePer Day
Pro6010,000
Enterprise300100,000

Exceeded limits return 429:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests",
    "retry_after": 30
  }
}

API Key Scopes​

Personal Keys​

  • Attached to your account
  • Access your tags only
  • Use for personal projects

Organization Keys​

  • Attached to organization
  • Access organization resources
  • Share with team (carefully)

Testing Authentication​

Verify Key Works​

curl https://api.tagd-ai.com/v1/me \
  -H "Authorization: Bearer YOUR_API_KEY"

Success response:

{
  "success": true,
  "data": {
    "id": "user_123",
    "email": "you@example.com",
    "plan": "pro"
  }
}

Troubleshooting​

Key Not Working​

  1. Check key is copied correctly (no extra spaces)
  2. Verify key is enabled
  3. Check IP restrictions
  4. Confirm permissions
  5. Verify subscription is active

Permission Denied​

  1. Review key permissions
  2. Ensure resource is yours
  3. Check organization membership
  4. Verify endpoint requirements

Next Steps​