API Authentication

This guide explains how to authenticate with the ReplyLink API to build integrations and custom applications.

Authentication Methods

ReplyLink API supports two authentication methods:

1. **API Key Authentication**: Simple key-based authentication for server-side applications

1. **OAuth 2.0**: Complete authorization flow for applications acting on behalf of users

API Key Authentication

Generating an API Key

1. Log in to your ReplyLink dashboard

1. Navigate to **Settings > API Keys**

1. Click "Generate New API Key"

1. Name your key and select the appropriate permission scopes

1. Store the generated key securely; it won't be displayed again

Using the API Key

Include your API key in the request header:

curl https://api.replylink.com/v1/automations   -H "Authorization: Bearer YOUR_API_KEY"

API Key Security

To keep your API key secure:

• Never expose it in client-side code or public repositories

• Use environment variables to store the key in your applications

• Implement IP restrictions in the API key settings

• Rotate keys regularly (we recommend every 90 days)

OAuth 2.0 Authentication

For apps that act on behalf of ReplyLink users, use OAuth 2.0:

OAuth Flow Overview

1. Redirect users to ReplyLink's authorization URL

1. User approves your app's requested permissions

1. User is redirected back to your app with an authorization code

1. Exchange the code for an access token

1. Use the access token to make API requests

Step 1: Register Your Application

1. Go to **Settings > Developer > Applications**

1. Click "Register New Application"

1. Provide application details:

- Name

- Description

- Website URL

- Redirect URI(s)

- Requested scopes

1. Save your client ID and client secret

Step 2: Authorization Request

Redirect users to:

https://api.replylink.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read:automations write:messages

Step 3: Handle the Redirect

After authorization, we'll redirect to your URI with a code:

https://your-app.com/callback?code=AUTHORIZATION_CODE

Step 4: Exchange for Access Token

Make a POST request to exchange the code for tokens:

curl https://api.replylink.com/oauth/token   -X POST   -d "client_id=YOUR_CLIENT_ID"   -d "client_secret=YOUR_CLIENT_SECRET"   -d "code=AUTHORIZATION_CODE"   -d "redirect_uri=YOUR_REDIRECT_URI"   -d "grant_type=authorization_code"

This returns:

{
  "access_token": "ACCESS_TOKEN",
  "refresh_token": "REFRESH_TOKEN",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Step 5: Use the Access Token

Include the token in your API requests:

curl https://api.replylink.com/v1/user   -H "Authorization: Bearer ACCESS_TOKEN"

Step 6: Refresh Expired Tokens

Access tokens expire after the time specified in `expires_in`. Refresh them with:

curl https://api.replylink.com/oauth/token   -X POST   -d "client_id=YOUR_CLIENT_ID"   -d "client_secret=YOUR_CLIENT_SECRET"   -d "refresh_token=REFRESH_TOKEN"   -d "grant_type=refresh_token"

Available Scopes

| Scope | Description |

|-------|-------------|

| `read:user` | Read user profile information |

| `read:automations` | View automation configurations |

| `write:automations` | Create and modify automations |

| `read:messages` | View message history and templates |

| `write:messages` | Send messages and create templates |

| `read:analytics` | Access engagement analytics |

| `read:contacts` | View contact list and segments |

| `write:contacts` | Modify contacts and segments |

Request only the scopes your application needs.

Rate Limiting

The API implements rate limiting to prevent abuse:

• **Standard Rate**: 100 requests per minute per API key

• **Enhanced Rate**: 300 requests per minute (available on Agency plans)

• **Custom Rate**: Available for Enterprise customers

When you exceed the limit, the API returns a `429 Too Many Requests` response.

Rate limit headers included in responses:

• `X-RateLimit-Limit`: Requests allowed per time window

• `X-RateLimit-Remaining`: Requests remaining in current window

• `X-RateLimit-Reset`: Time when the limit resets (Unix timestamp)

Security Best Practices

For API Keys

• Store securely in environment variables

• Never commit to source control

• Implement key rotation

• Use the minimum required permissions

For OAuth Applications

• Store client secret securely

• Validate redirect URIs

• Store tokens securely

• Implement PKCE for mobile/SPA applications

• Refresh tokens before they expire

General Recommendations

• Use HTTPS for all requests

• Implement request signing for sensitive operations

• Monitor API usage for unusual patterns

• Handle errors gracefully and securely

Troubleshooting

Common Error Codes

| Code | Description | Solution |

|------|-------------|----------|

| 401 | Unauthorized | Check API key or token validity |

| 403 | Forbidden | Verify you have the required permissions |

| 429 | Too Many Requests | Implement rate limit handling and backoff |

Invalid Token Errors

If your token is rejected:

1. Check it hasn't expired

1. Verify it's being sent correctly in the header

1. Ensure it has the required scopes

1. Try refreshing the token

Support

For additional help with API authentication:

• Review detailed examples in our [API Reference](/help/api/reference)

• Contact api-support@replylink.com with specific issues

• Join our developer community on Discord

By following these authentication guidelines, you can securely interact with the ReplyLink API while maintaining the security of your application and user data.