Creating and refreshing an API token in ReadyCloud

1

Before continuing, be sure you are logged in to your ReadyCloud account and your user has Owner or  Administrator privileges in your ReadyCloud Team Settings :

2

You will need to create a new client in ReadyCloud for your App. To create a new client, click here.

3

In the App Name textbox, enter a descriptive name for your App. Click the + Add App button.

4

You will now see your new App listed. Below is an example:

Important: Note and save the following values from the above window.

• App Id
  This will be your App's client_id needed for creating and refreshing your access_token
  
• App Secret
  This will be your App's client_secret needed for refreshing your access_token

5

You will now create your authorization URL which accepts the following 3 parameters:

1. response_type (required) This argument must be set to “token”.
2. client_id (required) This is the App Id from Step 4 above.
3. scope (optional) Space-separated list of permissions to API resources that your application is requesting to access from the ReadyCloud account user. If omitted, all scopes will be requested (not recommended). Possible scopes: company, packaging, calendar, license_key,
   account, api_client,  tracking_number, contact, backup_config, order, note
   
   Below is an example authorization URL. Be sure to replace  {client_id} with the value you saved from Step 4 and add any necessary scopes to the end of the URL:
   
   

   https://www.readycloud.com/api/v1/oauth2/authorize?response_type=token&client_id={client_id}&scope=
   

6

Copy the URL created in Step 5 and paste it into a web browser. Click the Allow Access button to create the permissions for your  access_token :

7

On the next page, copy the URL out of the browser into a text editor. Below is an example:

https://www.readycloud.com/api/v1/oauth2/auth_code#access_token={access_token}&user=admin%yourcompany.com&refresh_token={refresh_token}&expires_in=31536000&scope=packaging-read_only+api_client+license_key-read_only+account+order-read_only+api_client-read_only+calendar+packaging+tracking_number+license_key+order+backup_config-read_only+company-read_only+calendar-read_only+note-read_only+backup_config+contact+company+note+account-read_only+contact-read_only&token_type=bearer

Important: Note and save the following values from the above URL.

• access_token This will be your Authorization Bearer Token for API requests made to ReadyCloud.
• refresh_token You will need this token along with client_id and client_secret from Step 4 to renew your token. The access_token will expire and need to be refreshed every 365 days.

2. Retrieving the Org ID

Next, you will need to make a GET request to retrieve the Org ID for your ReadyCloud account. Be sure to replace {access_token} with the appropriate value.

curl --location -g --request GET 'https://www.readycloud.com/api/v2/orgs/' \
--header 'Authorization: Bearer {access_token}'

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "url": "/api/v2/orgs/XXX/",
            "name": "Your Company",
    ...

In the url field, the last 3 characters before the trailing slash are the Org ID. In the example above, the Org ID or  {org_pk} is: XXX

The  {org_pk} must be included in your endpoint URL when making API requests.

3. Creating the Endpoint URL

It is highly recommended to use  Authorization Type: Bearer Token with your API requests rather than including the access_token in the URL query parameters.

Below is an example of an API request using your final endpoint URL for orders. Be sure to replace  {org_pk} and {access_token} with the appropriate value.

curl --location -g --request GET 'https://www.readycloud.com/api/v2/orgs/{org_pk}/orders/' \
--header 'Authorization: Bearer {access_token}'

You can now begin making requests to the ReadyCloud API. Please continue with the API documentation here: https://www.readycloud.com/static/api-doc/v2/02-apireference-v2-02-orders.html

4. Refreshing an Expired API Key

If you are receiving the following response when attempting to make an API call, then your  access_token  has expired and will need to be refreshed.

{"error": "invalid_token", "error_description": "Token is expired"}

You will need to refresh the access_token every 365 days. To refresh the token programmatically, you will need the following keys:

• refresh_token from Step 7 of Creating an API Key above.
• client_id and client_secret from Step 4 of Creating an API Key above.

Below is an example cURL request to refresh the  access_token:

curl -i -s -X POST --data 'grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}' "https://www.readycloud.com/api/v1/oauth2/token/"

Below is an example response. Note the  access_token remains unchanged but you will need to save the new refresh_token in the response for future renewal.

{"access_token": "{access_token}", "expires_in": 31536000, "token_type": "bearer", "refresh_token": "{refresh_token}"}