OneCloud

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).
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've 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'll 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 \
https://api.onecloud.io/v1/metadata/workspace

Refreshing your access token

When your access token has expired, you'll 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 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.

Getting Started with the OneCloud API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.