Refresh app's access without the user

Clients can maintain offline access to resources and continue operating on behalf of the user even after the user leaves and is no longer actively interacting with the app. Since the access tokens are short-lived, they need to be reissued once they expire. OAuth 2.0 enables applications to obtain new access tokens without requiring a user to authenticate by exchanging refresh tokens for new access tokens. By default, refresh tokens expire after 14 days unless rotated. The maximum period of time the refresh tokens can be rotated is 1 year.

For example, the Cloud hosting platform enables you to deploy your service on-demand or according to preset schedule. To deploy the service on your behalf, the hosting platform has maintain access by issuing new access token in exchange for refresh tokens.

Step 1: Obtain refresh tokens

In authentication flows, refresh tokens can be returned along with access and ID tokens in exchange for an auth code. See OIDC authorization code flow.

• In email magic link, email OTP, social login, and other Mosaic auth flows, Mosaic returns the refresh tokens automatically.
• In pure OIDC integrations, to ensure the refresh tokens are returned, the auth call to /oidc/auth must explicitly request the offline_access scope and set the prompt to consent .

Below is a sample request (breaks and spaces were added for readability):

  https://api.transmitsecurity.io/cis/oidc/auth?
    client_id=[CLIENT_ID]& // Client ID found in the app settings in the Admin Portal
    scope=openid%20offline_access& // Must include offline_access in addition to openid
    response_type=code&
    redirect_uri=[REDIRECT_URI]&  // Redirect URI found in the app settings in the Admin Portal
    prompt=consent // Allows obtaining user consent which is required for offline access

This returns an authorization code to your redirect URI upon successful authentication; otherwise, an error. The code should be exchanged for tokens by calling the /oidc/token endpoint. See Integrate login using OIDC for more details.

The /oidc/token returns the access token, ID token, and refresh token that should be stored in your application backend. For example:

{
  "access_token": "[ACCESS_TOKEN]",
  "id_token": "[ID_TOKEN]",
  "refresh_token": "[REFRESH_TOKEN]",
  "expires_in": 3600
}

Step 2: Request new access tokens

To issue a new user access token using the refresh token, send a POST request to the /oidc/token endpoint like the one below. The call returns new access and ID tokens which can be used for offline access. Since refresh tokens are rotated upon each use, a new refresh token is returned as well.

curl -i -X POST \
https://api.transmitsecurity.io/oidc/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d grant_type=refresh_token \ # Must be set to 'refresh token'
-d client_id=[CLIENT_ID] \ # Found in the app settings in the Admin Portal
-d client_secret=[CLIENT_SECRET] \ # Found in the app settings in the Admin Portal
-d refresh_token=[REFRESH_TOKEN] # Returned upon successful authentication

Next steps

By default, refresh tokens are valid for 14 days. The maximum period of time the app can operate in the offline mode without requesting a user to re-authenticate is 1 year. You can modify the access duration by creating a custom resource and targeting it during authentication. With resources, you can extend or reduce the length of the access token, refresh token, and the maximum rotation time. For each resource, the expirations are configured in the Resource settings.