The RingCentral token is an essential part of RingCentral platform API. If you want to invoke the RingCentral API, the first thing you need to do is to obtain an access token. In this article, we are going to cover a very important topic and that is how to manage your tokens. First we will introduce some fundamentals about what the RingCentral tokens are since not every reader is familiar with them; second we will talk about when you need to refresh your tokens; third we will dive in to some details about token lifecycles after refresh; and lastly we will cover some best practices for token persistence.
RingCentral tokens fundamentals
The RingCentral Platform API implements OAuth 2.0. When you authorize successfully with the RingCentral Platform API using either Auth Code flow or Password flow, you will typically get two tokens: an access token & a refresh token. For more details about getting new tokens, please read the official docs. Here is a sample response for password flow, quoted from official docs:
{
"access_token" : "U1BCMDFUMDRKV1MwMXxzLFSvXdw5PHMsVLEn_MrtcyxUsw",
"token_type" : "bearer",
"expires_in" : 7199,
"refresh_token" : "U1BCMDFUMDRKV1MwMXxzLFL4ec6A0XMsUv9wLriecyxS_w",
"refresh_token_expires_in" : 604799,
"owner_id" : "256440016"
}The access token is for you to “access” the RingCentral platform API which lets you retrieve data, update data, setup subscriptions…etc. By default, an access token expires in an hour.
A Refresh token is for you to do a “refresh” and retrieve a brand new access token and a refresh token. So that you will not lose access to the RingCentral platform API because of token expiration. By default, the refresh token expires in a week.
Why do you need to refresh tokens?
Please note that, not all applications need to refresh tokens. If your app only needs to start once and it won’t last longer than an hour. You don’t need to bother refreshing the token because a new access token is valid for as long as an hour. And if you are OK to let users go through Auth Code flow or Password flow every time they use your app, you probably don’t need to refresh tokens either, because you can just get new tokens every time. So when do you need to refresh tokens?
- If your access token is expired and you want to access the RingCentral platform API.
- If your refresh token is going to expire soon and you don’t want to let a user go through the authorization process again.
Case #1 is quite obvious. You need a valid access token to access the RingCentral Platform API.
Case #2 needs more explanation: since a refresh token expires in a week, if you don’t want a user to authorize your app every week, you need to refresh the tokens before the refresh token expires. And as long as you implement a proper token refresh and management strategy, in theory, you never need users to authorize your app again.
Token lifecycles after refresh
Access Token
After token refresh, the old access token becomes invalid immediately.If you try to use the old access token right after refreshing, you will receive the following error message “Access token corrupted”. After about 10 seconds, using the old access token generates the following error message “Token not found”.
Refresh Token
After token refresh, the old refresh token remains valid for a while, depends on you if you use the new access token or not.
If you use the new access token, the old refresh token will become invalid after a short while(I cannot provide any exact number here since the behavior may change, it could be seconds to minutes). Within that short while, you can refresh as many times as you want. But every time you refresh you will get the same access token. After that short while, refreshing it will generate the following error message “Token not found”.
If you don’t use the new access token, the old refresh token will remain valid for quite long time(I don’t know the maximum value for certain). You can refresh as many times as you want. But every time you refresh you will get the same access token.
Even an old refresh token remains valid for a while, every time you refresh you will get the same access token. Which means, the server side simply gives you a cached value of the first refresh. This is by design, in case you did the refresh but failed to receive the result due to some network issues. And you should be ready for the old refresh token to become invalid at any time(although it may remain usable for a while).
Conclusion
After the token refresh, both the old access token and the old refresh token become pretty “useless”. You probably should discard them as long as you have secured the new access token and new refresh token.
Token persistence
First things first, why do you need to persist the RingCentral tokens? Not every app needs to persist tokens.You need to persist tokens if you want the tokens to survive the app restart or even the computer reboot. For example, you created a web application and have users that authorized your app to access his/her RingCentral resources. What if the browser refreshes? What if the user reboots his laptop? In such cases, you’d better save tokens in to the browser cookies. So whenever your app starts, it could try to read the browser cookies for the saved tokens. Browser cookies are not the only place to save tokens, for some apps, you may save tokens on the file system or in database.
Do not forget to update the tokens persisted after doing a token refresh! As we said in the last section, the old access token and the old refresh token become useless after the token refresh, you need to replace them with a new access token and a new refresh token. If you forget to update browser cookies/file system/database after doing a token refresh, you will lose access to the latest tokens after the app restarts.
Summary
That concludes this article. We have talked about the RingCentral tokens, covered the following topics: 1) what they are 2) when to refresh them, 3) token lifecycle and 4) when & how to persist them. We hope you enjoyed reading this article and thank you for your time!
Please let us know what you think by leaving your questions and comments below. To learn even more about other features we have make sure to visit our developer site and if you’re ever stuck make sure to go to our developer forum.
Want to stay up to date and in the know about new APIs and features? Join our Game Changer Program and earn great rewards for building your skills and learning more about RingCentral!
