Read this article for guidance on retrying failed requests to JumpCloud's REST API, as well as best practices for structuring subsequent retry requests. Customizing retry mechanisms based on these recommendations will increase the reliability and dependability of your API calls.
Considerations:
JumpCloud currently utilizes two versions of APIs. Depending on the type of integration, it may be required to use bothV1andV2APIs. Please refer to each API doc to understand the functionality available in that API set.
Supported HTTP Request Methods
GET
POST
DELETE
PATCH
PUT
Response codes
200
400
401
402
403
404
409
429
500
API Key Rotation
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.
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’s 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.
Paginating
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.
Warning:
Sorting 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.
Authentication failures: An unauthorized API key is used to authenticate the request
Incorrect request type: An unsupported HTTP request operator at a given endpoint is being used
Unsupported request: The request itself cannot be processed, often due to missing or unsupported data values in the request
Temporary errors
Temporary errors will cause a request to fail temporarily or intermittently. Examples of temporary errors include:
Service Outage
Service Maintenance
Rate limiting
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.
Based on the category of error, the Retry rate & strategy can be determined. This is outlined in the following section: Retry rates
Retry Rates
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.
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.
The following table outlines retry recommendations based on error classification:
Error Code
Definition
Recommendation
4xx Class
Client error
Immediate retry not recommended. Issue lies within the request itself.
429
Rate limit exceeded
Apply sufficient backoff; retry with a considerably less frequent request rate before scaling.
5xx Class
Server error
Apply sufficient backoff; retry with a less frequent request rate. Refer tostatus.jumpcloud.comfor a possible maintenance window, or incident before scaling.
Retry Intervals
Retry requests should always feature a longer interval than the previous retry attempt. Best practice is to implement an exponential backoff to specify exact timing increases between retry requests. An example implementation of an exponential backoff would be to retry the request shortly after a failed attempt. Subsequent requests are recommended to be executed on an exponential basis. For example, if the specified retry interval is 30 seconds, the first retry occurs after 30 seconds. The second retry should occur after 60 seconds, the third retry after 120 seconds, the forth after 240 seconds, and so on. Inadequate retry intervals can prove detrimental for both troubleshooting and client-side error handling.
In addition to these guidelines, several consecutive failed requests should warrant further investigation within the request code before retry is attempted.
Troubleshooting
A JumpCloud service returns “403 Forbidden. Your IP has been blocked due to suspected abuse.”
Symptoms
When accessing a JumpCloud Service endpoint, the connection returns an error:
403 Forbidden. Your IP has been blocked due to suspected abuse, please contact[emailprotected]in order to get this issue resolved.
Cause
This error is returned when an IP has been blocked due to suspected abuse.
Resolution
Contact JumpCloud Supportso we can work with you regarding the reasons for the block and action needed to unblock the IP(s).
It is recommended to rotate API keys every 90 days. Because of these potential risks, Google recommends using the standard authentication flow instead of API Keys. However, there are limited cases where API keys are more appropriate.
JumpCloud currently utilizes two versions of APIs. Depending on the type of integration, it may be required to use both V1 and V2 APIs. Please refer to each API doc to understand the functionality available in that API set.
Log in to JumpCloud as an Administrator or Command Runner. In the Admin Portal, click your account initials displayed in the top-right and select My API Key from the drop down menu. If you haven't generated an API key yet, you will have the option to Generate New API Key.
What happens if you never rotate an API key? The longer a key is around, the more chances it has to get leaked or compromised. Not only that, but if an API key is never rotated it is guaranteed to work for any malicious party that finds it.
API keys are generally not considered secure; they are typically accessible to clients, making it easy for someone to steal an API key. Once the key is stolen, it has no expiration, so it may be used indefinitely, unless the project owner revokes or regenerates the key.
JumpCloud tracks authentication traffic, this includes things like when you log in to your device, access SSO applications, or LDAP/RADIUS authentication. System Insights reports telemetry on the device.
Okta and JumpCloud have very different architectures, designed for different types of customers. While Okta stays firmly in its secure IAM management lane, JumpCloud provides a more comprehensive all-in-one solution for mobile device management and security.
Cloud APIs are software programs that transfer data between cloud computing services, or between cloud services and on-premise applications. They represent a subset of application programming interfaces (APIs), an interface that facilitates the transfer of data between software programs.
When authenticating with an API key, you don't need to reference your account credentials. Instead, you pass the API key in the HTTP header of your authentication request. Each organization can have up to 20 API keys. API keys are associated with an organization and not individual users.
What are the drawbacks of using API keys to secure REST APIs? API keys can be difficult to manage, and they don't provide granular authorization control. If an API key is compromised, it can give an attacker access to all of the data that the API exposes.
Embedding API keys in code: This dangerous practice can unintentionally reveal your API keys to the public, especially if your code is shared on platforms like GitHub. If your code is accessible, so are your API keys, making them vulnerable to misuse by malicious actors.
By default, the API key lifetime is set to 0, which means that the keys will never expire. To ensure that your keys are frequently rotated and each key is unique when regenerated, you must specify a validity period that ranges between 1—525600 minutes.
Due to the nature of the AES-256-GCM encryption used, keys should be rotated before approximately 232 encryptions have been performed, following the guidelines of NIST publication 800-38D. As of Vault 1.7, Vault will automatically rotate the backend encryption key prior to reaching 232 encryption operations by default.
Introduction: My name is Msgr. Refugio Daniel, I am a fine, precious, encouraging, calm, glamorous, vivacious, friendly person who loves writing and wants to share my knowledge and understanding with you.
We notice you're using an ad blocker
Without advertising income, we can't keep making this site awesome for you.
