Welcome to the RingCentral Community

This answered has been updated to be more current.

Let me attempt to coalesce all the answers to this question into a single cohesive one. The reason for the error is simple, and the error message itself says it all: the access token being use to authenticate with the API is not valid.

However, before I continue with an explanation and an answer, permit me to lay some important semantic groundwork so that one can more easily understand my answer and our documentation.

For OAuth there are two "tokens" that come into play:

• Authorization code. An "authorization code," or "auth code" for short, is a short-lived token that is exchanged for an access token. We sometimes refer to this as an "auth token" as well.

• Access token. An "access token" is an actual API credential that is presented in REST API calls via the HTTP Authorization header. You may sometimes see us refer to this an "access key."

You will find that at RingCentral we often refer to both of the above as "tokens" and as a result are unintentionally ambiguous. So be mindful when reading documentation to disambiguate between these terms to avoid confusion.

Back to the question at hand. An access token can become invalid for a few reasons outlined below.

Token has expired Obviously, this is not the problem affecting the user in the original question, as they clearly state their access token has not expired. But for everyone else coming to this question, know that access token expiration is a common challenge faced by developers. Access tokens expire automatically after 24 hours. To keep them fresh, it is essential developers use the refresh token that was acquired when the access token was first issued in order to obtain a new access token.

Tyler Lui has written a stellar Medium post about token management best practices, so I won't burden this answer with all of those details. But suffice it to say, go read it.

Race condition when refreshing tokens One thing developers should be mindful of, as I think developers have a tendency to overlook this, is that the moment a refresh token is used to obtain a new access token, the old access token is immediately invalidated. Here is a scenario I have encountered on multiple occasions:

• A developer is doing the right thing: they have implemented a service that wakes up once every 12 hours or so, iterates over a list of access tokens and refreshes them in the background.

• Unbeknownst to them however is that there is an active session somewhere in which an access token is actively being used.

• So then when the refresh service refreshes the access token, the other session is disrupted because all of a sudden its access token becomes invalidated.

The resolution to this is to implement some kind of locking mechanism on access tokens. That way, while an access token is in use, other services will know not to refresh it.

Too many access tokens issued to the same user Another failure scenario relates to the fact that there is a five access token limit on the number of access tokens that can be issued to the same user and client ID at any point in time. The behavior of the system in this circumstance is not easy to intuit. When the sixth access token is issued under the same client ID and to the same user, the first access token (the oldest) is immediately invalidated.

This is less often a problem for developers utilizing the authorization code flow given the nature of that flow. However, if you are using JWT or even our now deprecated password grant, the probability your code may be impacted by this goes up. The reason is simple: every time you auth to the API via JWT or via a password a new access token is generated. If your code is authored in such a way that you are logging into the API frequently without re-using previous access tokens you have obtained, then you may be unnecessarily proliferating the number of access tokens for any given user. And then you end up hitting this five access token limit, causing older access tokens to be suddenly invalidated.

Sometimes this is happening because you have multiple services or processes all trying to perform various actions for the same user. To debug, audit your whole system looking for services that might be running at the same time. Consider staggering those services, find a way to share access tokens between services, or issue a different client ID and secret to each service running.