Creating and refreshing an API token in ReadyCloud

The ReadyCloud API provides read and write access to orders, boxes, items, addresses, and all the other major data stored and processed by ReadyCloud. It is a modern JSON-based RESTful API.

Version 2.0 of the API is a major upgrade that provides many new properties and features, while at the same time simplifying and improving the format. Field naming is better, fewer fields are ‘custom fields’ but instead fully formatted and documented properties and we have a new way to distinguish explicit and implicit data.

Sections

1. Creating an API Key

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. 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:

response_type (required) This argument must be set to “token”.
client_id (required) This is the App Id from Step 4 above.
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={clien
t_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%y
ourcompany.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+pack
aging+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}'

You will receive a response that looks similar to the below:

{
    "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}"}