Quick Start
Welcome to the Memberstack Admin REST API! This guide will help you get started with the server-side REST API that allows you to manage members, verify tokens, and perform other administrative tasks programmatically from your server.
- Access to your Memberstack secret key (found in your Memberstack dashboard under Developer → Keys & IDs)
- A server-side environment to make secure API requests
- For paid functionality, a Memberstack account with an active billing method is required
Authentication
The Memberstack Admin REST API uses secret keys to authenticate requests. These keys provide full access to your account, so they must be kept secure.
Secret Key Management
You can view and manage your API keys in the Memberstack dashboard under Developer → Keys & IDs. There are two types of keys:
Test Mode Keys
- Prefix:
sk_sb_ - Use for development and testing
- Limited to 50 test members
- No real charges processed
Live Mode Keys
- Prefix:
sk_ - Use for production environments
- No member limits
- Real charges processed
Your secret keys carry administrative privileges, so keep them secure and use them in server-side environments only! Never use your secret keys in publicly accessible places like:
- Webflow, WordPress, or other CMS platforms
- GitHub or other public repositories
- Client-side code (browser JavaScript)
- Mobile applications
Rate Limits
The Memberstack Admin REST API allows 25 requests per second per IP address (the limit is counted per calling IP, not per secret key). If you exceed it, you'll receive a 429 (Too Many Requests) response with a plain-text body; the RateLimit-* response headers show your remaining budget.
Making API Requests
Learn how to structure your API requests to the Memberstack Admin REST API.
Base URL
All API requests should be made to the following base URL:
https://admin.memberstack.comAuthentication Headers
Include your secret key in the X-API-KEY header with every request:
// Example using fetch
fetch('https://admin.memberstack.com/members', {
headers: {
'X-API-KEY': 'sk_sb_your_secret_key'
}
})
// Example using Axios
const axios = require('axios');
const API_KEY = process.env.MEMBERSTACK_SECRET_KEY;
const BASE_URL = 'https://admin.memberstack.com';
axios.get(`${BASE_URL}/members`, {
headers: {
'X-API-KEY': API_KEY
}
})- Always store your API key in environment variables
- Set proper content headers (
Content-Type: application/json) for POST/PATCH - Handle potential rate limiting with exponential backoff
- Implement proper error handling for all responses
Error Responses
How the Admin REST API reports errors, plus the status codes and error codes you can expect.
Errors raised by the API itself are returned as JSON with a code and a message. The exceptions are rate limiting (a 429 has the text body Too many requests, please try again later.) and a request to a path that does not exist (an HTML 404 page), so check the status code before parsing the body as JSON. In non-production environments a debug field containing a stack trace may also be present.
{
"code": "generic-message",
"message": "Human-readable description of what went wrong"
}Error Codes
For most errors the code is the literal string generic-message, so branch on the HTTP status and surface the message field. A few endpoints return a more specific code:
validation/invalid-secret-key, missing, malformed, or unrecognized secret keyvalidation/invalid-json, the request body is not valid JSONinvalid-email, creating or updating a member with an invalid emailemail-already-in-use, creating a member with, or changing a member's email to, an address another member already hasinvalid-password-too-short, creating a member with a password shorter than 8 characterstest-mode-member-limit-reached, creating a member with a test-mode key once the app has 50 test membersplan-not-found, adding a plan whose ID does not resolve to a plan on your appplan-not-free/already-have-plan, adding a paid plan, or a plan the member already hasno-plan-found, removing a plan the member does not haveINVALID_TOKEN,POST /members/verify-tokencould not verify the token
HTTP Status Codes
- 400, Bad request: invalid input, a malformed JSON body, or a missing / non-
sksecret key - 401, A correctly formatted secret key that does not match any app
- 404, Data Tables only: the table or record does not exist
- 413, Request body exceeds the 2 MB limit
- 429, Rate limit exceeded (25 requests per second)
Fetching a member that does not exist (GET /members/:id_or_email) is not treated as an error: it returns 200 with "data": null. Only Data Tables use 404 for missing resources.
Security Best Practices
Follow these best practices to ensure your integration with the Memberstack Admin REST API is secure.
- Store secret keys in environment variables or a secure vault system (like AWS Secrets Manager, Hashicorp Vault, etc.)
- Use different keys for development and production environments
- Consider implementing key rotation for enhanced security
- Limit key access to only necessary team members
- Only make API calls from secure server environments (Node.js, Python, Ruby, PHP, etc.)
- Never expose endpoints that directly proxy your secret key
- Use HTTPS for all API communication to ensure encryption of data in transit
- Implement proper validation and sanitization for any user input that influences API calls
- Implement proper error handling for all API responses
- Avoid exposing detailed error messages to clients that might reveal implementation details
- Log errors securely for debugging without exposing sensitive information
- Consider implementing retry logic with exponential backoff for transient errors
Example Implementation
Here's a secure example of implementing the Memberstack Admin REST API in a Node.js environment:
// secure-memberstack.js
const axios = require('axios');
require('dotenv').config();
// Load API key from environment variables
const API_KEY = process.env.MEMBERSTACK_SECRET_KEY;
if (!API_KEY) {
throw new Error('MEMBERSTACK_SECRET_KEY is not defined in environment variables');
}
// Create a configured axios instance
const memberstack = axios.create({
baseURL: 'https://admin.memberstack.com',
headers: {
'X-API-KEY': API_KEY,
'Content-Type': 'application/json'
}
});
// Add response interceptor for error handling
memberstack.interceptors.response.use(
response => response,
async error => {
// Handle rate limiting
if (error.response && error.response.status === 429) {
console.log('Rate limited. Retrying after delay...');
// Implement exponential backoff here
}
// Log error safely (without exposing sensitive data)
console.error('API Error:', {
status: error.response?.status,
url: error.config?.url,
method: error.config?.method
});
return Promise.reject(error);
}
);
// Export the configured client
module.exports = memberstack;