Rate Limiting, Pagination & Authentication

This section details the policies and mechanisms for controlling API usage, navigating large datasets, and securing your requests.

Authentication

All requests to our API must be authenticated using a Bearer Token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Obtaining a Token: API tokens are issued by your system administrator. Do not share your token.
Token Expiration: Tokens have a limited lifespan. Ensure your integration handles token refresh if applicable.
Security: Always transmit tokens over HTTPS. Do not hardcode tokens in client-side code.

Rate Limiting

To ensure fair usage and maintain API stability, we enforce rate limits on all endpoints.

Limits:
- Standard Endpoints: 100 requests per minute per IP address.
- Batch Endpoints: 10 requests per minute per IP address.
Headers:
- X-RateLimit-Limit: The maximum number of requests allowed in the current window.
- X-RateLimit-Remaining: The number of requests remaining in the current window.
- X-RateLimit-Reset: The time (in UTC epoch seconds) when the current rate limit window resets.
Exceeding Limits: If you exceed the rate limit, you will receive a 429 Too Many Requests HTTP status code.

Pagination

For endpoints that return large datasets, we use cursor-based pagination to allow efficient retrieval of results.

Parameters:
- limit: (Optional) The maximum number of items to return per page. Default is 20, maximum is 100.
- cursor: (Optional) A string representing the starting point for the next set of results.

Example Request:

GET /products?limit=50&cursor=eyJpZCI6IjEyMyIsImNyZWF0ZWRBdCI6IjIwMjQtMDctMjRUMTA6MDA6MDBaIn0=

Response Structure:

{
  "data": [
    // array of resource objects
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IjQ1NiIsImNyZWF0ZWRBdCI6IjIwMjQtMDctMjRUMTE6MDA6MDBaIn0=",
    "has_more": true
  }
}

The next_cursor should be used in the subsequent request to fetch the next page of results. If has_more is false, there are no more results.