Skip to main content

Creating API Keys

API keys authenticate your applications with tagd-ai. This guide walks through creating and managing keys.

Prerequisites​

  • Pro or Enterprise subscription
  • Account owner or admin access

Create Your First Key​

Step 1: Access API Settings​

  1. Sign in to tagd-ai
  2. Click avatar → Settings
  3. Select API Keys

Step 2: Create New Key​

  1. Click Create API Key
  2. Fill in details:
    • Name: Descriptive name (e.g., "Production Server")
    • Description: Optional notes

Step 3: Select Permissions​

Choose what this key can access:

Tag Permissions:

  • ☑️ tags:read - Read tags
  • ☐ tags:write - Create/update tags
  • ☐ tags:delete - Delete tags

File Permissions:

  • ☑️ files:read - Download files
  • ☐ files:write - Upload files

Other:

  • ☐ webhooks:read - List webhooks
  • ☐ webhooks:write - Manage webhooks
  • ☐ analytics:read - View analytics

Step 4: Configure Options​

Optional settings:

  • IP Restrictions: Limit to specific IPs
  • Expiration: Auto-expire after date
  • Rate Limit: Custom rate limit (Enterprise)

Step 5: Generate Key​

  1. Click Create Key
  2. Copy the key immediately
  3. Key shown only once
  4. Store securely

Key Naming Conventions​

Use clear, descriptive names:

Good names:

  • Production-App-Server
  • Development-Local
  • CI-CD-Pipeline
  • Analytics-Dashboard

Bad names:

  • key1
  • test
  • my key

Permission Templates​

Read-Only Access​

For analytics dashboards:

☑️ tags:read
☑️ files:read
☑️ analytics:read

Full Tag Management​

For content management:

☑️ tags:read
☑️ tags:write
☑️ tags:delete
☑️ files:read
☑️ files:write

Webhook Management​

For integration setup:

☑️ tags:read
☑️ webhooks:read
☑️ webhooks:write

Complete Access​

For admin tools:

☑️ All permissions

Managing Keys​

View All Keys​

Go to API Keys to see:

  • Key name
  • Permissions summary
  • Created date
  • Last used
  • Status

Key Details​

Click a key to view:

  • Full permission list
  • Usage statistics
  • IP restrictions
  • Expiration date

Edit Key​

Modify existing key:

  1. Click the key
  2. Click Edit
  3. Change name, description, permissions
  4. Save changes

Note: Key value cannot be changed. Regenerate for new value.

Disable Key​

Temporarily stop a key:

  1. Find the key
  2. Click the toggle or Disable
  3. Requests fail immediately
  4. Re-enable anytime

Delete Key​

Permanently remove:

  1. Click the key
  2. Click Delete
  3. Type key name to confirm
  4. Key cannot be recovered

Regenerating Keys​

Get a new key value (same settings):

  1. Click the key
  2. Click Regenerate
  3. Confirm action
  4. Copy new key immediately
  5. Update your applications

Old key stops working instantly.

IP Restrictions​

Limit where key can be used:

Add IP Whitelist​

  1. Edit the key
  2. Go to IP Restrictions
  3. Add IPs: 
    192.168.1.100
    10.0.0.0/8
  4. Save

IP Formats​

  • Single IP: 192.168.1.1
  • CIDR range: 192.168.0.0/16
  • Multiple entries allowed

Testing IP Restrictions​

  1. Make request from allowed IP ✅
  2. Make request from other IP ❌ 403 error

Key Expiration​

Set automatic expiration:

  1. Edit the key
  2. Set Expiration Date
  3. Save

On expiration:

  • Key stops working
  • Email notification sent
  • Can extend before expiration

Multiple Keys​

Why Use Multiple Keys​

  • Different permissions per service
  • Easy revocation per service
  • Better security isolation
  • Clearer usage tracking

Example Setup​

Key NameUsePermissions
Web-AppMain websitetags:read, write
AnalyticsDashboardtags:read, analytics:read
CI-CDDeploymenttags:write, webhooks:write
MobileMobile apptags:read, files:read

Key Limits​

Per-plan key limits:

PlanMax Keys
Pro10
EnterpriseUnlimited

Test vs Production Keys​

Test Keys​

  • Prefix: tagd_test_
  • Use sandbox environment
  • No real data affected
  • For development only

Production Keys​

  • Prefix: tagd_live_
  • Access real data
  • Use in production apps
  • Keep highly secure

Storing Keys Securely​

Environment Variables​

# .env (never commit)
TAGD_API_KEY=tagd_live_xxxxx

Secret Managers​

Use services like:

  • AWS Secrets Manager
  • Google Secret Manager
  • Azure Key Vault
  • HashiCorp Vault

What NOT to Do​

  • ❌ Commit to Git
  • ❌ Include in client-side code
  • ❌ Share via email/chat
  • ❌ Hardcode in source files

Troubleshooting​

Can't Create Key​

  • Verify Pro/Enterprise subscription
  • Check you have account admin access
  • Ensure within key limit

Key Not Working​

  • Copy includes full key
  • No extra whitespace
  • Key is enabled
  • Permissions include needed access
  • Check IP restrictions

Next Steps​