API Authentication

The Gately API uses API key authentication. Your API key contains the project context, so authentication is simple and straightforward.

API Keys

API keys are used for all API communication. They provide full access to your project’s data and automatically include the project context.

Creating an API Key

Go to your Gately dashboard
Navigate to Settings > API Keys
Click Create API Key
Give your key a descriptive name
Copy and securely store the key (it won’t be shown again)

Using API Keys

Include the API key in the Authorization header:

curl -X GET "https://api.usegately.com/api/v1/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

Never expose API keys in client-side code. They should only be used in server-side applications.

API Key Prefixes

Prefix	Environment
`gately_sk_live_`	Production
`gately_sk_test_`	Test/Development

JWT Tokens (Client-side)

JWT tokens are used for client-side authentication when users log in to your application.

Obtaining a JWT Token

const { session } = await gately.login('user@example.com', 'password')
const token = session.access_token

Using JWT Tokens

curl -X GET "https://api.usegately.com/api/v1/user/profile" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Expiry

Token Type	Expiry
Access Token	1 hour
Refresh Token	7 days

Refreshing Tokens

const { session } = await gately.refreshSession()

Or via API:

curl -X POST "https://api.usegately.com/api/v1/auth/refresh" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your-refresh-token"}'

Authentication Summary

Method	Authorization Header	Use Case
API Key	`Bearer gately_xxxxx`	Server-to-server
JWT Token	`Bearer eyJhbG...`	Client-side apps

Security Best Practices

Rotate API Keys Regularly

Create new API keys periodically and revoke old ones to minimize risk.

Use Environment Variables

Store API keys in environment variables, never in source code.

Limit Key Permissions

Create separate keys for different services with minimal required permissions.

Monitor Usage

Regularly review API key usage in your dashboard to detect anomalies.

Error Responses

Invalid Token

{
  "success": false,
  "error": "Invalid or expired token",
  "code": "INVALID_TOKEN"
}

Missing Authentication

{
  "success": false,
  "error": "Authentication required",
  "code": "AUTH_REQUIRED"
}

Overview

Authentication

Members

Project Settings

Email Campaigns

Plans

Contacts

Discussions

Transactional Email

Webhooks

API Keys

Creating an API Key

Using API Keys

API Key Prefixes

JWT Tokens (Client-side)

Obtaining a JWT Token

Using JWT Tokens

Token Expiry

Refreshing Tokens

Authentication Summary

Security Best Practices

Error Responses

Invalid Token

Missing Authentication

​API Keys

​Creating an API Key

​Using API Keys

​API Key Prefixes

​JWT Tokens (Client-side)

​Obtaining a JWT Token

​Using JWT Tokens

​Token Expiry

​Refreshing Tokens

​Authentication Summary

​Security Best Practices

​Error Responses

​Invalid Token

​Missing Authentication

API Keys

Creating an API Key

Using API Keys

API Key Prefixes

JWT Tokens (Client-side)

Obtaining a JWT Token

Using JWT Tokens

Token Expiry

Refreshing Tokens

Authentication Summary

Security Best Practices

Error Responses

Invalid Token

Missing Authentication