When to pass refresh token to API

Question

I am trying to access an authorization server that issues short lived access tokens and longer lived refresh tokens when a user presents a username and password.

1. Should the client pass the refresh token on every call to the API along with the access token or should the client only pass the refresh token once they receive an error code from the API that the access token has expired?
2. What type of error code is passed back to the client once the refresh token has expired? This would mean the client needs to request a new access token by passing the username and password again.

Satsuma

Answer 1

Question 1:

Should the client pass the refresh token on every call to the API along with the access token or should the client only pass the refresh token once they receive an error code from the API that the access token has expired?

The client does not need the Refresh Token until the Access Token has expired. Every call needs the Access Token, but only a request to grant a new Access Token needs the Refresh Token.

To obtain a new Access Token, you send a request with the grant_type set to refresh_token, as in section 6 of the RFC.
Ideally, you'd ask for a new Access Token before the current Access Token has expired, so as not to interrupt the service.

Most implementations I've seen issue a new Refresh Token with every Access Token. You can use any valid Refresh Token to obtain a new Access Token.

Question 2:

What type of error code is passed back to the client once the refresh token has expired? This would mean the client needs to request a new access token by passing the username and password again.

Unfortunately, the RFC does not explicitly define the error response; see section 7.2 of the RFC:

If a resource access request fails, the resource server SHOULD inform the client of the error. While the specifics of such error responses are beyond the scope of this specification, this document establishes a common registry in Section 11.4 for error values to be shared among OAuth token authentication schemes.

So, the exact response depends on the server. It should be defined by the server in question.

If the server offers new Refresh Tokens, you'll want to get a new Refresh Token before the current one expires.

You do not want to send the user's credentials again; you're not supposed to have them, let alone keep them. OAuth 2 was designed to allow third parties access to a user's protected resources without seeing the user's credentials.

You will usually get a new Refresh Token with a new Access Token, in a password_grant or a refresh_token call. The RFC does not guarantee this though.
If the server does not give new Refresh Tokens, or cannot be relied upon to give new Refresh Tokens, you will have to ask the user to log in again. Note that this logging in is done via the Authorization Server, which is not necessarily your application. In fact, it's probably not.

Neonatal

I see what your saying about the access token expiring, however, eventually the refresh token will expire. At that point the client will need to re-authenticate with credentials. – Satsuma

@Satsuma I've updated my answer. Most of the time, the expiry time of a refresh token is much longer than a session. In these cases, it's not a problem to ask the user to log in again. – Neonatal