API Keys

API keys are used to authenticate your applications with Gately. There are two types of keys for different use cases.

Testing the API? Once you have an API key, you can test any endpoint directly in our docs using the interactive playground on each API page.

API Key Types

Key Type	Prefix	Usage	Security
Public Key	`gately_pk_`	Browser/client-side apps	Safe to expose in frontend code
Secret Key	`gately_sk_`	Server-side only	Never expose publicly

Never expose secret keys (gately_sk_) in client-side code. Use public keys for browser applications and secret keys only on the server.

Creating API Keys

Via Dashboard

Navigate to Settings → API Keys in your Gately dashboard
Click Create API Key
Choose the key type:
- Public Key - For frontend/browser applications
- Secret Key - For backend/server applications
Enter a descriptive name (e.g., “Production Frontend”, “Backend API”)
Click Create
Copy the key immediately - it won’t be shown again

After creating your API key, head to any API endpoint page (like List Members) and use the playground to test it!

API Key Format

Public Key

gately_pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Secret Key

gately_sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Part	Description
`gately`	Prefix identifying Gately keys
`pk` / `sk`	Public key / Secret key
`live`	Environment (live or test)
`xxxx...`	Unique key identifier

Usage Examples

Browser / Client-Side (Public Key)

import { GatelyClient } from '@gately/sdk'

// Safe to use in frontend code
const gately = new GatelyClient({
  apiKey: 'gately_pk_live_xxxxxxxx'
})

// Login user
await gately.login('user@example.com', 'password')

React

import { GatelyProvider, useGately } from '@gately/sdk'

function App() {
  return (
    <GatelyProvider apiKey="gately_pk_live_xxxxxxxx">
      <YourApp />
    </GatelyProvider>
  )
}

function LoginButton() {
  const { login } = useGately()
  return <button onClick={() => login('user@example.com', 'pass')}>Login</button>
}

CDN / Script Tag

<script 
  src="https://cdn.usegately.com/gately.min.js" 
  data-api-key="gately_pk_live_xxxxxxxx"
  defer
></script>

Node.js / Server-Side (Secret Key)

import { GatelyNodeClient } from '@gately/sdk/node'

// Use secret key on server only
const gately = new GatelyNodeClient({
  apiKey: process.env.GATELY_SECRET_KEY // gately_sk_live_xxxxxxxx
})

// Server-side operations
const members = await gately.listMembers()
const member = await gately.createMember({
  email: 'user@example.com',
  full_name: 'John Doe'
})

REST API (Secret Key)

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

Python

import os
import requests

API_KEY = os.environ['GATELY_SECRET_KEY']

def get_members():
    response = requests.get(
        'https://api.usegately.com/api/v1/members',
        headers={
            'Authorization': f'Bearer {API_KEY}'
        }
    )
    return response.json()

Permissions

Secret API keys can be scoped to specific permissions:

Permission	Description
`read:members`	View member data
`write:members`	Create, update, delete members
`read:content`	View protected content
`write:content`	Manage protected content
`read:campaigns`	View campaigns and stats
`write:campaigns`	Create and send campaigns
`read:contacts`	View contacts and lists
`write:contacts`	Create and manage contacts
`admin`	Full access to all resources

Public keys have limited permissions by default (authentication and user profile access).

Managing API Keys

List All Keys

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

Response:

{
  "success": true,
  "data": [
    {
      "id": "key_123",
      "name": "Production Frontend",
      "type": "public",
      "prefix": "gately_pk_live_abc",
      "created_at": "2024-01-15T10:00:00Z",
      "last_used_at": "2024-01-20T15:30:00Z"
    },
    {
      "id": "key_456",
      "name": "Backend API",
      "type": "secret",
      "prefix": "gately_sk_live_xyz",
      "permissions": ["admin"],
      "created_at": "2024-01-15T10:00:00Z",
      "last_used_at": "2024-01-20T15:30:00Z"
    }
  ]
}

Revoke a Key

curl -X DELETE "https://api.usegately.com/api/v1/api-keys/key_123" \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

Environment Variables

Store your API keys in environment variables:

# .env.local (for development)
NEXT_PUBLIC_GATELY_API_KEY=gately_pk_live_xxxxxxxx
GATELY_SECRET_KEY=gately_sk_live_xxxxxxxx

// Frontend (public key)
const gately = new GatelyClient({
  apiKey: process.env.NEXT_PUBLIC_GATELY_API_KEY
})

// Backend (secret key)
const gately = new GatelyNodeClient({
  apiKey: process.env.GATELY_SECRET_KEY
})

Security Best Practices

Use the Right Key Type

Use public keys (gately_pk_) for frontend apps and secret keys (gately_sk_) for backend only.

Never Expose Secret Keys

Secret keys should never appear in frontend code, mobile apps, or public repositories.

Use Environment Variables

Store API keys in environment variables or a secrets manager, not in source code.

Rotate Regularly

Create new keys and revoke old ones periodically, especially after team member departures.

Use Minimal Permissions

Create secret keys with only the permissions needed for their specific use case.

Monitor Usage

Review API key usage in your dashboard to detect unauthorized access.

Rate Limits

API keys are subject to rate limiting:

Plan	Requests/Minute
Free	60
Pro	300
Business	1000
Enterprise	Custom

Troubleshooting

401 Unauthorized

Verify the API key is correct and not revoked
Check that you’re using the right key type for your environment
Ensure the Authorization header format is correct: Bearer YOUR_KEY

403 Forbidden

The API key doesn’t have permission for this action
Public keys have limited permissions - use a secret key for admin operations
Create a new key with the required permissions

429 Rate Limited

You’ve exceeded the rate limit
Wait for the reset time or upgrade your plan

Invalid API Key Format

Ensure your key starts with gately_pk_ or gately_sk_
Check for extra spaces or characters when copying

Overview

Authentication

Members

Project Settings

Email Campaigns

Plans

Contacts

Discussions

Transactional Email

Webhooks

API Key Types

Creating API Keys

Via Dashboard

API Key Format

Public Key

Secret Key

Usage Examples

Browser / Client-Side (Public Key)

React

CDN / Script Tag

Node.js / Server-Side (Secret Key)

REST API (Secret Key)

Python

Permissions

Managing API Keys

List All Keys

Revoke a Key

Environment Variables

Security Best Practices

Rate Limits

Troubleshooting

​API Key Types

​Creating API Keys

​Via Dashboard

​API Key Format

​Public Key

​Secret Key

​Usage Examples

​Browser / Client-Side (Public Key)

​React

​CDN / Script Tag

​Node.js / Server-Side (Secret Key)

​REST API (Secret Key)

​Python

​Permissions

​Managing API Keys

​List All Keys

​Revoke a Key

​Environment Variables

​Security Best Practices

​Rate Limits

​Troubleshooting

API Key Types

Creating API Keys

Via Dashboard

API Key Format

Public Key

Secret Key

Usage Examples

Browser / Client-Side (Public Key)

React

CDN / Script Tag

Node.js / Server-Side (Secret Key)

REST API (Secret Key)

Python

Permissions

Managing API Keys

List All Keys

Revoke a Key

Environment Variables

Security Best Practices

Rate Limits

Troubleshooting