SocialRails
Public APIAPI Authentication

API Authentication

Learn how to authenticate with the SocialRails Public API using API keys, including scopes and security best practices.

The SocialRails API uses API keys for authentication. Every request must include a valid API key in the Authorization header.

Creating an API Key

  1. Go to Dashboard > Settings > API
  2. Click Create Key
  3. Enter a descriptive name (e.g., "Zapier Integration", "Content Bot")
  4. Select the scopes your integration needs
  5. Click Create Key
  6. Copy your key immediately, it is only displayed once

Your key will look like: sr_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456789abc

Using Your API Key

Include the key in the Authorization header with the Bearer prefix:

Authorization: Bearer sr_live_your_key_here

Example with curl:

curl -X GET https://socialrails.com/api/v1/posts \
  -H "Authorization: Bearer sr_live_your_key_here"

Testing Your Key

After creating a key, verify it works by hitting the health endpoint (no auth needed) and then a protected endpoint:

# 1. Verify the API is reachable (no auth required)
curl https://socialrails.com/api/v1/health
 
# 2. Test your API key
curl https://socialrails.com/api/v1/workspace \
  -H "Authorization: Bearer sr_live_your_key_here"

If your key is valid, you'll see your workspace name and plan info. If not, you'll get a 401 UNAUTHORIZED error.

Scopes

Each API key has one or more scopes that control what it can access:

ScopePermissions
readList posts, view analytics, list accounts, view workspace info
writeCreate, update, and delete posts; upload media
aiUse AI content generation (deducts AI credits from your plan)
webhooksRegister and manage webhook subscriptions

Select only the scopes your integration actually needs. A key with read scope cannot create posts. A key without ai scope cannot use the AI generation endpoint.

Security Best Practices

  • Never expose your API key in client-side code, Only use API keys in server-side code or secure environments.
  • Use separate keys for each integration, This limits the blast radius if a key is compromised.
  • Rotate keys regularly, Revoke old keys and create new ones periodically.
  • Use the minimum required scopes, Don't grant write or ai access if your integration only reads data.
  • Monitor usage, Check the API request logs in your dashboard to spot unusual activity.

Key Management

  • View keys: Dashboard > Settings > API, shows all keys with their prefix and creation date
  • Revoke a key: Click the trash icon next to any active key to immediately deactivate it
  • Key limits: The number of active keys depends on your plan (2 for Creator, up to 10 for Agency)

Authentication Errors

StatusCodeMeaning
401UNAUTHORIZEDMissing, invalid, or expired API key
403FORBIDDENAPI access not available on your plan, or key lacks required scope

Frequently Asked Questions

Can I see my full API key after creating it?
No. The full API key is only shown once, right after you create it. After that, only the prefix (first few characters) is visible in your dashboard. If you lose your key, delete it and create a new one.
What happens when my API key expires?
Expired keys stop working immediately. Any request made with an expired key returns a 401 UNAUTHORIZED error. Create a new key from your dashboard to restore access.
Can I change the scopes on an existing API key?
No. Scopes are set when the key is created and cannot be changed afterward. To change scopes, delete the old key and create a new one with the scopes you need.
Is there a limit on how many API keys I can create?
Yes. The limit depends on your plan: Creator allows 2 keys, Business allows 5, and Agency allows 10. Delete unused keys to free up slots.
<- API Changelog