Help Desk

Submit a ticket My Tickets

Getting Started with the OneCloud API

OneCloud allows for users to access their data and interact with chains via our external REST API. 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.

API Access

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.

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 --header "Content-Type: application/json" \
			--header "Authorization: Bearer YOUR_ACCESS_TOKEN"
			--request GET \

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:

curl -d '{"grant_type":"refresh_token", "client_id": "YOUR_CLIENT_ID", "refresh_token":"YOUR_REFRESH_TOKEN"}' \
			-H "Content-Type: application/json" \
			-X POST

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 (\).

curl -d "{\"grant_type\":\"refresh_token\", \"client_id\": \"YOUR_CLIENT_ID\", \"refresh_token\":\"YOUR_REFRESH_TOKEN\"}" -H "Content-Type: application/json" -X POST

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!

OneCloud is the author of this solution article.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.