All requests are authenticated via an access token that is passed in via a request header. In order to start using our API, you must first enable API access for a user.

📓 Currently, a user must be an administrator in order to access the API

Enable API Access

When logged in as an admin user, navigate to the Admin section and click on the API card to go to the API access page. From here, there will be a button labeled "Enable API Access". Click this button to generate an API application for your user, which will create an Access Token and a Refresh Token

.

Store the Tokens

💥 After navigating away from this page, tokens will no longer be visible.

After enabling API access, the access token and refresh token should appear on the page. Be sure to take note of these tokens. They are only returned to the user upon creation.

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 to be treated as ephemeral. They are only valid for a limited amount of time. Once the access token has expired, users must use a refresh token to get a new access token.


Access Token: The access token will expire after 24 hours (1 day) by default. If someone wishes to extend the amount of time for which their token is valid, click the dropdown at the bottom left of the API section to open the advanced settings. There, they may can choose how many days your token will last. Be careful when using this setting - an API token can be very powerful, and it should be stored securely.


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 Limit

Update 6/19/21: Currently, users are limited to making 50,000 requests to the API within a 24 hour period. There is also a burst limit - no more than 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-burst-remaining - the number of requests remaining in the 20 second burst period

  • oc-api-daily-remaining - the number of requests remaining in the current 24 hour window

Using the Access Token

Once the access token has been generated, keep it safe! With this token, users can view metadata in your workspaces and execute chains. Access can be revoked at any time by going into the API page in the platform 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 the access token has expired, users will receive an unauthorized response from the API. Not to worry - with the refresh token, users can generate a new access token. Simply 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/token

Windows 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

Refresh Tokens are Single-Use

Upon using a refresh token, the server will respond with the associated access token and a brand new refresh token. Be sure to store the new refresh token along with the access 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

Did this answer your question?