Piano supports a three-legged OAuth process. This allows clients using Identity Management to retrieve tokens that authenticate user identities and grant third-party applications access to Piano resources on behalf of those users — making it easy to give users access to e-editions or other external applications. More information on this is available here.
All available base URLs for Production are listed here.
Below are the steps to refresh the access token.
1. Get the authorization code (if you don't have one yet):
GET https://id.piano.io/id/api/v1/identity/authorize?response_type=code&client_id=SrmTGdXwNo&redirect_uri=<REDIRECT_URI>
For example, you will get a browser redirect to: redirect_uri/?code=CODE1
2. Using this code, you can make a POST request to get the access token:
POST https://id.piano.io/id/api/v1/identity/token
Content-Type: application/x-www-form-urlencoded
client_id=SrmTGdXwNo&client_secret=<OAUTH_CLIENT_SECRET>&redirect_uri=<REDIRECT_URI>&grant_type=authorization_code&code=<CODE1>
Use the code value received in Step 1 as the code parameter.
3. The response will contain the refresh_token value:
{
"access_token": "abc",
"token_type": "Bearer",
"refresh_token": "CODE2",
"expires_in": 86352,
"email_confirmation_required": false
}
4. At this point, either check for access using one of the methods described here, or proceed to the next step.
To refresh the access token, make a POST request:
POST https://id.piano.io/id/api/v1/identity/token
Content-Type: application/x-www-form-urlencoded
client_id=SrmTGdXwNo&grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>
Use the refresh_token from Step 3 (e.g. CODE2).
5. The response will contain a new refresh_token and a refreshed access token. The expiration duration is set in your Identity Management configuration.
{
"access_token": "xyz",
"token_type": "Bearer",
"refresh_token": "CODE3",
"expires_in": 86400,
"email_confirmation_required": false
}
6. To refresh again, repeat the POST request using the refresh_token from the previous step (in this example, CODE3):
POST https://id.piano.io/id/api/v1/identity/token
Content-Type: application/x-www-form-urlencoded
client_id=SrmTGdXwNo&grant_type=refresh_token&refresh_token=<CODE3>
7. Repeat this process each time the access token needs to be refreshed.