- \n
- JumpCloud currently utilizes two versions of APIs. Depending on the type of integration, it may be required to use both V1<\/a> and V2<\/a> APIs. Please refer to each API doc to understand the functionality available in that API set.<\/li>\n<\/ul>\n\n\n\n
Supported HTTP Request Methods<\/strong><\/p>\n\n\n\n
- \n
- GET<\/li>\n\n\n\n
- POST<\/li>\n\n\n\n
- DELETE<\/li>\n\n\n\n
- PATCH<\/li>\n\n\n\n
- PUT<\/li>\n<\/ul>\n\n\n\n
Response codes<\/strong><\/p>\n\n\n\n
- \n
- 200, 201, 202, 204<\/li>\n\n\n\n
- 302, 303, 304<\/li>\n\n\n\n
- 400, 401, 402, 403, 404, 406, 409, 410, 412, 415, 422, 428, 429<\/li>\n\n\n\n
- 500, 502, 503, 504<\/li>\n<\/ul>\n\n\n\n
API Key Rotation<\/h2>\n\n\n\n
Because API keys are utilized in the development of solutions that interact with the JumpCloud API, and thus are sometimes shared, there are opportunities for these private API keys to be compromised.<\/p>\n\n\n\n
Best security practice strongly encourages the API Key associated with your JumpCloud Administrator account to be rotated & re-generated on a periodic rolling basis. While specific security needs and risks will vary for your organization, it\u2019s generally recommended to re-create the API keys on an annual basis. Note that once an API key is rotated, the older key will be invalidated. Code that leverages older API keys will fail and will need to be updated with the new key.<\/p>\n\n\n\n
You can also set an expiration for the API Keys, see JumpCloud APIs<\/a> to learn more. <\/p>\n\n\n\n
Paginating<\/h2>\n\n\n\n
When paginating results with “skip” or querying with a “filter”, it is highly recommended that you also add “sort” : “_id” to the query parameters. Sorting will ensure that you receive all and only the requested data (i.e., no missing or duplicate results). If you choose to sort by a different field, be sure that field contains unique values.<\/p>\n\n\n\n
![](\"\/wp-content\/themes\/jumpcloud\/assets\/images\/gutenberg-blocks\/warning-icon.png\")
<\/p><\/div>Warning:<\/strong> \nSorting on fields that contain duplicate values may return a different sort order for those duplicate fields over multiple executions, especially when the collection is actively receiving writes.<\/p>\n <\/div><\/div><\/div><\/div>\n\n\n\n
Error Handling<\/strong><\/h2>\n\n\n\n
Request errors, regardless of source, can be categorized as Permanent or Temporary errors.<\/p>\n\n\n\n
Permanent errors<\/h3>\n\n\n\n
Permanent errors will cause a request to always fail. Examples of Permanent errors include:<\/p>\n\n\n\n
- \n
- Authentication failures: An unauthorized API key is used to authenticate the request<\/li>\n\n\n\n
- Incorrect request type: An unsupported HTTP request operator at a given endpoint is being used <\/li>\n\n\n\n
- Unsupported request: The request itself cannot be processed, often due to missing or unsupported data values in the request<\/li>\n<\/ul>\n\n\n\n
Temporary errors<\/h3>\n\n\n\n
Temporary errors will cause a request to fail temporarily or intermittently. Examples of temporary errors include:<\/p>\n\n\n\n
- \n
- Service Outage<\/li>\n\n\n\n
- Service Maintenance<\/li>\n\n\n\n
- Rate limiting<\/li>\n<\/ul>\n\n\n\n
An example of a temporary error would be an HTTP error in the 5xx class. This error can be surfaced if the request is made to an endpoint that may be currently unavailable.<\/p>\n\n\n\n
Based on the category of error, the Retry rate & strategy can be determined. This is outlined in the following section: Retry rates<\/p>\n\n\n\n
Retry Rates<\/h2>\n\n\n\n
All network components can be responsible for returning errors. These errors are commonly derived from network hiccups on the server or client, a service disruption on incident, or scheduled maintenance. <\/p>\n\n\n\n
Retry mechanisms are useful for increased reliability and consistency when leveraging JumpCloud APIs. Should a request return an error, correctly configured retry mechanisms ensure that the failed request is retried with consideration to the error response.<\/p>\n\n\n\n
The following table outlines retry recommendations based on error classification:<\/p>\n\n\n\n