API Key Management

Manage your API keys to securely authenticate API requests to TextFlow.

What are API Keys?

API keys are authentication tokens that allow your applications to interact with the TextFlow API. Each key is unique to your organization and grants access to send SMS messages and manage resources programmatically.

API Key Types

TextFlow supports two types of API keys:

Production Keys (sk_live_*)

• Use for: Live production environments
• Prefix: sk_live_
• Billing: Messages count toward your subscription limits
• Example: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Protect Production Keys

Production keys should only be used in secure server environments. Never expose them in client-side code, mobile apps, or public repositories.

Test Keys (sk_test_*)

• Use for: Development and testing
• Prefix: sk_test_
• Billing: Messages do not count toward limits (test mode)
• Example: sk_test_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Development Best Practice

Always use test keys during development. This prevents accidental charges and allows unlimited testing without affecting your production message limits.

Creating an API Key

1. Log in to your TextFlow account
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Enter a descriptive name (e.g., “Production Server”, “Development”)
5. Select environment: Production or Test
6. Click Create
7. Copy the key immediately - it will only be shown once

Save Your Key Immediately

API keys are only displayed once when created. If you lose a key, you’ll need to generate a new one. Store keys securely using a password manager or secrets management system.

Managing API Keys

Viewing API Keys

Your API keys page displays:

• Key prefix: First 16 characters (e.g., sk_live_a1b2c3d4)
• Name: Descriptive name you assigned
• Environment: Production or Test
• Last used: Timestamp of most recent API call
• Status: Active or Revoked
• Created: When the key was generated

Note

The full API key is never displayed after creation for security reasons. Only the prefix is shown to help identify keys.

Revoking API Keys

To immediately disable an API key:

1. Go to Settings → API Keys
2. Find the key you want to revoke
3. Click Revoke
4. Confirm the action

Revoked keys:

• ✅ Stop working immediately
• ✅ Return 401 Unauthorized errors
• ✅ Can be permanently deleted
• ❌ Cannot be reactivated (create a new key instead)

When to Revoke

Revoke a key immediately if:

• It was accidentally exposed (committed to Git, shared in a screenshot, etc.)
• An employee who had access leaves the company
• You’re rotating keys as part of regular security maintenance
• A key hasn’t been used in over 90 days

Regenerating API Keys

To replace an existing key with a new one:

1. Go to Settings → API Keys
2. Find the key you want to regenerate
3. Click Regenerate
4. Copy the new key immediately
5. Update your application with the new key

This is useful when:

• You want to rotate keys without changing the name/description
• The old key was compromised
• You’re implementing key rotation as a security policy

Caution

The old key stops working immediately after regeneration. Update your applications before regenerating to avoid downtime.

Deleting API Keys

To permanently remove a revoked API key:

1. Go to Settings → API Keys
2. Find the revoked key
3. Click Delete
4. Confirm permanent deletion

Note

Only revoked keys can be deleted. Active keys must be revoked first. This prevents accidental deletion of keys in use.

API Key Security

Best Practices

1. Use Environment Variables

   # .env file
   TEXTFLOW_API_KEY=sk_live_your_api_key_here

   Never hardcode API keys in your source code.

2. Separate Keys by Environment

   • Use different keys for development, staging, and production
   • Never use production keys in development environments

3. Limit Key Access

   • Only share keys with team members who need them
   • Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, etc.)
   • Never commit keys to version control

4. Rotate Keys Regularly

   • Change production keys every 90 days
   • Document key rotation procedures
   • Use calendar reminders for scheduled rotations

5. Monitor Key Usage

   • Check “Last used” timestamps regularly
   • Revoke keys that haven’t been used in 90+ days
   • Set up alerts for unusual API activity

What NOT to Do

❌ Don’t commit keys to Git:

// BAD - Don't do this!
const apiKey = 'sk_live_a1b2c3d4e5f6g7h8'; // Hardcoded key

❌ Don’t expose keys in client-side code:

<!-- BAD - Don't do this! -->
<script>
  const API_KEY = 'sk_live_a1b2c3d4e5f6g7h8';
</script>

❌ Don’t share keys in screenshots, support tickets, or chat messages

❌ Don’t use the same key across multiple applications

What TO Do

✅ Do use environment variables:

// GOOD
const apiKey = process.env.TEXTFLOW_API_KEY;

✅ Do use server-side API calls:

// GOOD - Server-side API route
app.post('/api/send-sms', async (req, res) => {
  const apiKey = process.env.TEXTFLOW_API_KEY;
  // Make API call with key
});

✅ Do use a .gitignore file:

.gitignore

.env
.env.local
secrets/

✅ Do store keys in a secrets manager for production deployments

API Key Permissions

All API keys have the same permissions:

• ✅ Send SMS messages via API
• ✅ View message delivery status
• ✅ Access organization resources (contacts, campaigns)
• ❌ Cannot create/modify users or billing settings

Role-Based Access

API keys inherit the permissions of your organization. User-level permissions (admin, manager, staff) are enforced separately through the web dashboard authentication.

Troubleshooting

”API key required”

Cause: The X-API-Key header is missing from your request.

Solution: Add the header to all API requests:

curl -X POST https://textflow.telair.net/api/v1/messages/send \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"to": "+15551234567", "message": "Test"}'

“Invalid API key format”

Cause: The key doesn’t start with sk_live_ or sk_test_.

Solution:

• Check that you copied the entire key
• Verify there are no extra spaces or line breaks
• Ensure you’re using the correct environment variable

”Invalid or inactive API key”

Cause: The key was revoked, deleted, or doesn’t exist.

Solution:

• Check the API Keys page to see if the key is active
• Generate a new key if the old one was revoked
• Verify you’re using the correct key for this account

Key not working after creation

Cause: Possible caching or environment variable issues.

Solution:

• Restart your application to reload environment variables
• Clear any application caches
• Verify the key was copied correctly (check for trailing spaces)

“Last used” timestamp not updating

Cause: The key might not be making successful API calls.

Solution:

• Check your application logs for API errors
• Verify the key is being sent in the X-API-Key header
• Test with a simple curl command to confirm the key works

Rate Limiting

API keys are subject to rate limits based on your subscription plan:

Plan	Per-Minute Limit	Daily Limit
Starter	100 requests/min	5,000 messages
Marketer	300 requests/min	25,000 messages
Enterprise	Custom	Custom

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response. Implement exponential backoff and retry logic in your applications.

Monitoring API Usage

Check API usage in your dashboard:

1. Go to Dashboard
2. View API Activity section
3. See recent API calls, success rates, and errors

You can also see per-key usage:

1. Go to Settings → API Keys
2. Check the Last used column
3. Click on a key to view detailed usage stats

Compliance & Data Security

• Encryption: API keys are hashed using SHA-256 before storage
• HTTPS Only: All API requests must use HTTPS (TLS 1.2+)
• No Logging: Full API keys are never logged in plain text
• Compliance: Meets SOC 2, GDPR, and CASL requirements

Next Steps

• Send your first API request →
• View code examples →
• Learn about rate limiting →