Using Spiro's API

The full API documentation can be found here.

Generating an Access Token

OAuth 2.0 protocol with Refresh Token flow is used for authentication. To generate a valid access token, first create a new authorization from the API Tokens tab under settings in the Spiro app. You must provide a valid redirect URI, and once you click save a client ID and client secret will be generated. There will also be an "Authorize" button which will prompt you to enter your Spiro login credentials, and will then redirect you to the redirect URI you provided with an authorization code parameter (if you are authorizing in your browser, you will see the code appended to the url in the url bar). You can then use the client_id, client_secret, code, redirect_uri to execute a POST request to https://engine.spiro.ai/oauth/token with the header "Content-Type":"application/json" and the following request body:

{
"client_id": "XXX",
"client_secret": "XXX",
"code": "XXX",
"redirect_uri": "XXX",
"grant_type": "authorization_code"
}

An access_token and a refresh_token will be returned. The default lifespan of the access_token is 24 hours, at which point you should use the refresh_token to generate a new access_token.

Refreshing your Access Token

To refresh your access token, execute a POST request to POST https://engine.spiro.ai/oauth/token with the header "Content-Type":"application/json" and the following request body:

{
"client_id": "XXX",
"client_secret": "XXX",
"refresh_token": "XXX",
 "grant_type": "refresh_token"
}

Authentication uses refresh token rotation, which means that for every access token refresh request, it will issue a new refresh token. Previous tokens are invalidated (revoked) only once the access token is used. Make sure to store the new refresh_token after the refresh token request. (edited)

This diagram walks you through the process described above:

Screen_Shot_2018-07-09_at_12.02.21_PM.png

Using the API

Each tab on the left-hand side of the API interface mirrors a class of features in Spiro. Under each class of features, there is a list of endpoints that can be used to retrieve, create, update, or delete data via HTTP request protocol. Clicking on the endpoint in the API interface opens a built-in test development environment which specifies the URI, request method (GET, POST, DELETE, or PUT), and parameters. Additionally, developers can actually call the resource example from the environment, and see an example request syntax and infrastructure in several programming languages. The API Reference can be found here.