- Only administrators can access the API.
Generate and store tokens
While logged in as an administrator:
- Go to the Admin section.
- Click on the API card to go to the API access page.
- Click the Enable API Access button.
This will create an Access Token and a Refresh Token for your user. It's important to take note of these tokens, as they are only returned to the user upon creation.
Note: Tokens will no longer be visible after leaving this page.
OAuth protocol
OneCloud's API follows the OAuth2 specification for authentication, which is an industry-standard protocol. An access token is used to authenticate your request. The API will check that the token belongs to an active OneCloud user and that the token itself is not expired.
API V1 time limits
Access tokens are only valid for a limited amount of time. Once the access token has expired, a refresh token is needed to get a new access token.
- Access Token: The access token will expire after 24 hours (1 day) by default. You can extend this time by clicking the dropdown menu at the bottom left of the API section and opening the advanced settings.
- Refresh Token: The refresh token is valid for one use only. Upon using your refresh token to get a new access token, the response will also include your new refresh token.
Rate limits
The following limits apply:
- Users are limited to 50,000 requests to the API within a 24 hour period.
- There is a burst limit of 100 requests within a 20 second period.
Should these limits be exceeded, users will receive a 422 Rate limit exceeded response.
The following headers will be available on each response, letting users know how many more requests they can make before reaching the limit:
-
oc-api-daily-remaining: The number of requests remaining in the current 24 hour window.
- oc-api-burst-remaining: The number of requests remaining in the 20 second burst period.
Using the access token
Make sure your access token is securely stored. With this token, users can view metadata in your workspaces and execute chains.
Access can be revoked at any time by returning to the API page and clicking the Revoke API Access button. Users' API access will also be removed automatically when their accounts are disabled.
When making requests to the API, the access token must be used as a Bearer token in the authorization header. See the example below (note that you will have to replace "YOUR_ACCESS_TOKEN" with the access token you generated earlier):
cURL
curl --header "Content-Type: application/json" \
--header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--request GET https://api.onecloud.io/v1/metadata/workspace
Refreshing the access token
When an access token has expired, users will receive an unauthorized response from the API. The single-use refresh token must now be used to generate a new access token.
When the refresh token is used, the server will respond with the associated access token as well as a new refresh token. Be sure to securely store both of these.
Here's how to send a request to the API with your refresh token, client ID, and the grant type:
Linux
curl -d '{"grant_type":"refresh_token", "client_id": "YOUR_CLIENT_ID", "refresh_token":"YOUR_REFRESH_TOKEN"}' \
-H "Content-Type: application/json" \
-X POST https://api.onecloud.io/oauth/tokenWindows does not support single quotes (') in command-line execution. The payload (-d) must be enclosed in double-quotes ("), and the double quotes within the payload must be escaped using the backslash (\).
Windows
curl -d "{\"grant_type\":\"refresh_token\", \"client_id\": \"YOUR_CLIENT_ID\", \"refresh_token\":\"YOUR_REFRESH_TOKEN\"}" -H "Content-Type: application/json" -X POST https://api.onecloud.io/oauth/token
Get Started with OneCloud Documentation
To start making requests, check out our API Reference for the list of available endpoints and the ability to make test requests.
Detailed API documentation can be found at: https://api.onecloud.io/
Chain
Workspace
Environments
Execution
Security