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.
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.
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.
Advanced input for access token expiration for personal API tokens
Allows specifying the amount of time an access token is valid for. Additionally, the API token limits can be set via an environment variable. Example: API_REQUEST_LIMIT=1000
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:
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 (\).