Introduction
Overview of the Members API and how to use it.
URL
The base URL for the API is https://api.members.dev.
Trailing slashes are optional on URLs. For example, both https://api.members.dev/v1/users and https://api.members.dev/v1/users/ are valid.
Authentication
The Members API uses API keys to authenticate requests. Every request must include a valid API key in the Authorization header as the Bearer token unless otherwise specified. For example:
curl -X GET "https://api.members.dev/v1/users" \
-H "Authorization: Bearer <your-api-key>"You can view and manage your API keys in the Members.dev dashboard. After you create your first API key through the dashboard, you will be able to use it to create and manage additional API keys using the API Keys endpoints.
API keys allow access to your Members.dev account, including your users' data. Take precautions to keep them secure. Crucially, do not expose your API key in client-side code. We suggest creating your own server-side API/actions which securely routes API requests to Members.dev, which you can then call from your client-side code.
Every request must be made over HTTPS. Requests made over plain HTTP will fail.
Unauthenticated requets will be rejected with a 401 Unauthorized response.
Errors
We use conventional HTTP status codes to indicate the success or failure of a request:
- Codes in the 2xx range indicate successful requests.
- Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a value was invalid, an issue with authentication, etc.).
- Codes in the 5xx range indicate an error with Members.dev's servers, which we strive to avoid.
If any error is unclear, please conctact us at support@members.dev and we'll do our best to help you.
Pagination
Most top-level resources have endpoints to return multiple records, like list users and list subscriptions. These endpoints are paginated using a common offset pagination pattern. This allows you to access specific pages of results. Items are sorted in reverse chronological order by default.
Use the optional query parameters page to specify the page number you want to retrieve, and size to specify the number of items per page. You can access a maximum of 100 items per page.
The response will include the following:
items: The list of records retrieved.total: The total number of items, after applying any filters.page: The current page number.size: The number of items per page.pages: The total number of pages, after applying any filters.
Rate Limits
We have a default rate limit of 100 requests per minute. If you exceed this limit, you will receive a 429 Too Many Requests response.
The 429 response will include headers:
Retry-After: The number of seconds you should wait before retrying the request.X-RateLimit-Reset: The unix timestamp at which the current rate limit window resets.
If you need a higher rate limit, please contact us at support@members.dev.
External IDs
Some items, like Users, have a external_id property which can be used to link an entity in your own system to one in Members.dev.
These objects have endpoints to retrive them by their external ID, instead of having to use the List endpoint and filtering by external ID.
External IDs must always be unique for each object. An error will be returned if you try to create an object with an external ID that already exists. If you need to store duplicate external IDs, you should use the metadata property instead.
Versioning
Keeping with best REST API practices, the Members API is versioned in case we need to make breaking changes in the future. The current version is v1. All paths are prefixed with the version number. For example, the Users endpoint is GET /v1/users.
Feedback
We always love to hear from any developers using Members.dev, especially if you have frustrations or suggestions to improve the API or documentation. Please reach out to us at support@members.dev and we'll do our best to help you.
Useful Links
- Access the Dashboard to generate your first API key
- Contact us at support@members.dev if you have any questions or feedback