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 your tokens

After enabling API access, you should see your access token and refresh token appear on the page. Be sure to take note of these tokens. They are only returned to the user upon creation, and after navigating away from this page, you will no longer be able to see your tokens.

OAuth Protocol

Our 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, and once your access token has expired, you must use a refresh token to get a new access token.


Access Token: Your access token will expire after 24 hours (1 day) by default. If you wish to extend the amount of time for which your token is valid, click the dropdown at the bottom left of the API section to open the advanced settings. Here, you 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: Your 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 - you cannot make more than 100 requests within a 20 second period. Should you exceed these limits, you will receive a 422 Rate limit exceeded response.

The following headers will be available on each response, letting you know how many more requests you 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 your Access Token

Once you have generated your access token, 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 your access token

When your access token has expired, you will receive an unauthorized response from the API. Not to worry - with your refresh token, you 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 can only be used once

Upon using a refresh token, the server will respond with your access token and a brand new refresh token. Be sure to store the new refresh token along with your access token!

See our docs to get started

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?