We’ve developed some resources to help you work effectively from home during COVID-19 Click to learn more

Refresh tokens

In this article

    Refresh tokens are used in token-based authentication to get new ID tokens and access tokens when those expire.

    A refresh token is essentially a user credential giving infinite authentication. It improves the user experience, especially in native applications.

    How is the refresh token used?

    The refresh token is sent in the request to get a new ID token and/or access token: 

    • when the access (or ID) token has expired
    • when you want to update the claims in an ID token

    You should only see the refresh token in the authentication code flow, with or without PKCE. Never for single-page applications using the implicit flow.

    A refresh_token is used in a POST request as follows:

    POST Request (can be tested in a client such as Postman or Fiddler)
    
    https://{env}.superoffice.com/login/common/oauth/tokens?
    grant_type=refresh_token&
    client_id=4ref5376616343b38d14ddcd804f2654&
    client_secret=18f45229e442772a78df5f554e24a456&
    refresh_token=nKHwerkjh34Yd6QShsnGKk4cFhTwCv3XtJu9PW2X63MtUMygLdI57BJjwCU0&
    redirect_url=http://localhost/callback
    
    Refresh token parameters
    Parameter Required Description
    grant_type yes Must be set to refresh_token
    client_id yes The client ID (application ID) assigned to your app when you registered it with SuperOffice.
    client_secret yes The client secret (application token) assigned to your app when you registered it with SuperOffice.
    refresh_token yes The refresh token issued as one of the response items in the authorization code flow.
    redirect_uri no The redirect_uri of your app, where authentication responses are sent and received by your app.
    It must exactly match one of the redirect_uris registered with SuperOffice.
    scope no SuperOffice only supports the scope openid, and is implicit for each flow.

    The response contains the token type, access token, expiration in seconds, and identity token.

    {
    "token_type": "Bearer",
    "access_token": "8A:Cust12345.AZuHwfgrRZPHqdjhQyay34ggAgAA8z5BnSYUSk4U4sdfr1Bjzycu0S1NC+xvghQ4VoUz9r6xpF2YAOCj0rb3LWnjLqllp3fYk8h2sxwc8d+5nb5bzGvHLHJ1UIRk38Ye4dPpmLSr4B8UaYNc9gs4Wgfgxqtii+o5w5XTYhPFW1rTcqbXbsnAtv8S+tJWHGPDxi2T/XUHpZxaDp2FT50nVePNiT9tAfP9QQwH0hbXN6RZzKfOcX37DtGcigMLsoc1qM+bJ8oWJqhVbPQIQ4J7DFj5Nr76ecH7rVwpBqxNsOYrek+iLo+KNUovSljIzOXp16y62E5hhs0e+ePThKSS7h52iaq5cwQMj0u2EAInK80UUjRTTpwznJWSlCFXsOD+cSNC6livOOz54PJoejKS+VxRqsr3TYQK+IZbfdxV2MHAtVATpeJOva/aa3XZXiNwSZHPYIZr7fvFnvuTvGJTRSvOR2TuZhy2wl6/qOTLSpG9gvtPD2zjC+BiVmMW/P4Qhv3DWoSFCVqyQISqtFXy3rGexPIL+dz7kutoSkDYhcAl6aO8B0kdYKSsPow+8Jo8N3SD453r9uTGGiAl1tVWXfHo53ehuLJzjtFey4OEn0hJ1YqCybSS9hF2sb5+v2HF36RPpt6bqOuCEIMAcpYJkiQ87kLTqsEGA9AA43sf1RfcB7lbVaVLFGmjUj1jgtIzVKiAR9eyMiWXL3dWMg+WM2Y0MOTsUrSb10kXkJ4g3M4TvH3rV4HTK3ohToxUleYvFbarx/8jeO7oLJfn3nth8NGtd1lJ",
    "expires_in": 3600,
    "id_token": "eyJ0eFor_Demonstration_PurposeszI1NiIsIng1dCI6IkZyZjdqRC1hc0dpRnFBREdUbVRKZkVxMTZZdyJ9.For_Demonstration_PurposesbSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9hc3NvY2lhdGVpZCI6IjUiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvaWRlbnRpdHlwcm92aWRlciI6ImNlbnRyYWwtc3VwZXJpZCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9lbWFpbCI6InRvbnlAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L3VwbiI6InRvbnlAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L2N0eCI6IkN1c3QyNjc1OSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9pc19hZG1pbmlzdHJhdG9yIjoiRmFsc2UiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvc2VyaWFsIjoiMTgwMTU1MDE5MyIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9uZXRzZXJ2ZXJfdXJsIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tL0N1c3QyNjc1OS9SZW1vdGUvU2VydmljZXM4Ni8iLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvd2ViYXBpX3VybCI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbS9DdXN0MjY3NTkvYXBpLyIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9zeXN0ZW1fdG9rZW4iOiJTdXBlck9mZmljZSBEZXZOZXQgTm9kZSBPSURDLThrOFE3RG1CZ28iLCJpYXQiOiIxNTQ2NjEzMTk4IiwiaXNzIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tIiwiYXVkIjoiNmNmMjUzNzY2MTYzNDNiMzhkMTRkZGNkODA0ZjI4OTEiLCJleHAiOjE1NDY2MTM0OTgsIm5iZiI6MTU0NjYxMzEzOH0.ZzeDsNHJr86pLyqvpPQ5rMzRGd88Fh_RHLdBuG8fBmk_iZnFI5zaARDsTQffEzM30l61rZVmmpQo7KfAN6w27QB6XawURYwye59Z5c3fWRg8BJ4K5Uwik3PxtXtl4A4NWFgZPYyw6t6ZR7kdFng4CQBG0D8I1jF2YZrI8ZO33PtRPisYHJ1F2F5O-qStzCXqhSjd1u7FjsJhqr1xGLDqLzkOm9_0v0nWFHESjBuPhFPIdt6lmcCuy48HGg5G0eM1_3h6SESsukXe0hNMqp3ZHjm5dCEoxE4HziLWSdRZIUa6tkP6wfHDHU_XUJu7PHo8Wx5aG9IBPZ_r1Xd8mgmt6g"
    }

     

    Where does the refresh token come from?

    You will receive the refresh token in the authorization response when the application user asks for access for the 1st time.

    It is up to the application to securely store the refresh token. This is usually done in a session. Refresh tokens must never be stored client-side in the browser!

    We might revoke a refresh token if we suspect its security has been compromised. 

    When does the refresh token expire?

    This is a long-lived token that is coupled to a user's consent and that can be re-used.

    • for the lifetime of the application, or
    • as long as the application authorization record (consent) exists, or
    • until it has been revoked - tenants can revoke authorizations