What causes "Unknown or invalid refresh token." error?

Using the REST API usually involves managing access and refresh tokens. A common pattern is to retrieve an authentication token using the login endpoint and store the authentication token and the refresh token that are returned. The authentication token is valid for 12 hours. After 12 hours, it expires, and the refresh token is used to get an updated authentication token.

Refresh tokens do not have an expire time. However, it is still possible for the token to be deleted, resulting in the refresh token call getting this error:

{"error":"invalid_grant","error_description":"Unknown or invalid refresh token."}

This happens when there are more than 200 active refresh tokens for a user. AWS will delete tokens on an oldest-first basis. A refresh token is generated with every login, so after 200 logins, tokens will start being deleted. It is not possible to restore a deleted refresh token. Instead, perform a login and use the refresh token that is returned.

Best practice is to be sure to store the newest refresh token after every login and use that updated value in any subsequent refresh actions.