> ## Documentation Index > Fetch the complete documentation index at: https://docs.superoffice.com/llms.txt > Use this file to discover all available pages before exploring further. # Authorization Code flow > Introduction to the Authorization Code flow. Authorization Code flow is the best flow to use for web applications. When it was first introduced Authorization code flow required the client\_secret. However, on a windows or mobile application that causes security problems. Proof Key for Code Exchange (PKCE) ([rfc7636][5]) was introduced as extra layer of security on top of Authorization Code flow, and provides a way for native applications to use Authorization Code flow without exposing the client\_secret in a vulnerable way. PKCE does not replace the use of a client secret for all scenarios, and in fact PKCE is recommended even when a client is securely using the client secret. ## Getting the user's consent OAuth is about enabling users to grant access to applications, and allowing those application access to their SuperOffice web services. The Authorization Code flow begins when a client application redirects a user to the [authorize endpoint][2]. ```http theme={null} # test in a browser to handle the login/redirect GET Request https://sod.superoffice.com/login/common/oauth/authorize? client_id=c789b7d98f3c496fb5aaa4b1a81ca11b& scope=openid& redirect_uri=https://[registered-application-redirect_uri]/callback& state=12345& response_type=code& ``` ### Authorization Code flow parameters | Parameter | Required | Description | | ----------------------- | :---------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `client_id` | yes | The client ID (application ID) assigned to your app when you registered it with SuperOffice. | | `scope` | yes | Must be `openid`. | | `redirect_uri` | yes | The [redirection endpoint][1] of your app, where authentication responses are sent and received.
It must exactly match one of the redirect URIs for your registered application. | | `state` | recommended | A value set by the Relying Party to maintain state between the request and the callback itself. Included in the request and also returned in the token response. | | `response_type` | yes | Must include `code` for the Authorization Code flow. | | `acr_values` | no | Allows passing in additional related information. SuperOffice allows `tenant:contextIdentifer`, i.e. tenant:Cust12345, used to skip the tenant selection dialog | | `response_mode` | no | Can be one of:
`fragment` and returns parameters in the URI after hash #
`form_post` and returns values in form data | | `login_hint` | no | Hint to the Authorization Server about the login identifier the user might use to sign in. For SuperOffice, this must be **SuperID username**. When used, it updates the user's name in the login cookie and is displayed in the username field. (added June 2019) | | `code_challenge` | with PKCE | **Required for PKCE only.** (added January 2020) | | `code_challenge_method` | no | **Optional for PKCE only.** Defaults to "plain" if not present in the request. Code verifier transformation method is "S256" or "plain". (added January 2020) | The user is then directed to the SuperOffice SuperID **sign-in screen**, where they enter their credentials. An identity provider authenticates the user and asks for consent to access their resources on behalf of the Relying Party (app). ## Redirect back to the application When successfully authenticated and consent given, **SuperID** sends a response that redirects the user agent back to the Relying Party (app) redirect\_uri. The response includes an **Authorization Code** and any state provided by the client earlier. ```http theme={null} GET https://partnerapp/callback? state=12345& code=o0NWI5leHdUflrjlTVVKqbSOt3n9Od0ZrBUq0nXFWKszyOdOZchk60fTf4pDWTFT ``` ### Authorization Code response | Parameter | Description | | --------- | -------------------------------------------------------------------------------------------- | | code | The Authorization Code generated by the Authorization Server.
Expires after 10 minutes. | | state | The exact value received from the client. | ## Exchange the authorization code for an access token This is the final step, where the Relying Party (app) requests an access token. ```http theme={null} # can be tested in an HTTP client (such as Postman, Fiddler or VS Code) POST https://sod.superoffice.com/login/common/oauth/tokens? client_id=c789b7d98f3c496fb5aaa4b1a81ca11b& client_secret=83d0f3bcb9afbc7eb9d0682e9b86db52& code=o0NWI5leHdUflrjlTVVKqbSOt3n9Od0ZrBUq0nXFWKszyOdOZchk60fTf4pDWTFT& redirect_uri=http://partner-app/callback& grant_type=authorization_code& Content-Type: application/x-www-form-urlencoded Accept: application/json ``` ## Authorization Code request | Parameter | Required | Description | | --------------- | :-------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client_id` | yes | The ID assigned to your application when you registered it with SuperOffice. | | `client_secret` | yes | The **application secret** (token) assigned to your application when you registered it with SuperOffice. | | `code` | yes | The Authorization Code that the application requested.
The application can use the Authorization Code to request an access token for the target resource. | | `redirect_uri` | yes | The redirect endpoint of your application, where authentication responses are sent and received by your app.
It must exactly match one of the redirect URIs registered with SuperOffice. | | `grant_type` | yes | Must be `authorization_code` for the Authorization Code flow. | | `code_verifier` | with PKCE | **Required for PKCE only.** (added January 2020) | The identity provider (central-superid) will verify all the parameters, ensuring the client ID and secret match and the code hasn't expired. When that's complete, it will generate an access token and send it in the response. ### Post response ```http theme={null} POST Response { "token_type": "Bearer", "access_token": "8A:Cust12020.AR2s3phb0gXK8DP0NfoYlsrQAQAACIJ/KQ+cbGp0l9g8PJNlBCEZxS/1hL3Cxt8ITWlQipRbdt5CL1lQmUotYHaQQH9/Y7nq98WduG7QuSY7KMiSQRxHn7W5qppkEjlSTLW2+xfaV42eL2Vvw6V2WVwICzP6iE6wUDvVX8Zgbp757BdKY4mIRnxsaGtpFGBFwKASLiLJ69SoUnYz753mx6XCwTFtgZRywCKDwykXLFoQ5qgAbhCkxs7IFmcBszRIgAAdul49zG/iAho24yw6fgcz/J+TpxVE/CpSsXsdDV/JpSA96ny9SQQ97t8HeRvCG5FuUdE8TvzKorwIbccEvAGbsjRNsH0iKCP1BsnPUIRdq6f3iQf2R+LVEN1XqvxE7JsbF9cYwQ0IWtW3hfFy8BanBvqbYFYQcHLC3Qq/KTIJF8jZeV0djYoM8fzVY/hkLavIKWHXQnVWU7Vw/yTWHpu+5xUTjJbHEhyduDImLNvOCPXzRQpQgso7agBMUEHzTXyTE348g1OZA32SfnAWwXMh/AvLZ1IQ0m5rzRcM1g3AolEmJWm3+2wPY5pmV6D6N3JTGgUA+b6USonaknTbIFxUuUChHj4U1qUlP6/dJA+aKE1psfT8F4XwFlYBjvw6xmM086Vckm0Mmh+fEPuoLsp+EgtQzD0F8Ka4qLFGWICvUg==", "expires_in": 3600, "refresh_token": "KSamN1Tp4sd26pZJSGK6JobrWOUWorIZ2Y5XxcAqX86K9qoZRp4d3lUH32F4fiT3", "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IkZyZjdqRC1hc0dpRnFBREdUbVRKZkVxMTZZdyJ9eyJzdWIiOiJ0b255LnlhdGVzQHN1cGVyb2ZmaWNlLmNvbSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9hc3NvY2lhdGVpZCI6IjUiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvaWRlbnRpdHlwcm92aWRlcI6InN1cGVyb2ZmaWNlLW9ubGluZSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9lbWFpbCI6InRvbnkueWF0ZXNAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L3VwbiI6InRvbnkeWF0ZXNAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L2N0eCI6IkN1c3QxMjAyMCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9pc19hZG1pbmlzdHJhdG9yIjoiRmFsc2UiLCJodRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvc2VyaWFsIjoiMTUwMTE3ODU4NCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9uZXRzZXJ2ZXJfdXJsIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tL0N1c3QxMjAMC9SZW1vdGUvU2VydmljZXM4Mi8iLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvd2ViYXBpX3VybCI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbS9DdXN0MTIwMjAvYXBpLyIsImlhdCI6IjE1MTYyOTk2NTYiLCJub25jZSI6IjczNJDQUVBLTlDQTUtNEI0My05QkEzLTM0RDdDMzAzRUJBNyIsImlzcyI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbSIsImF1ZCI6ImRiMTgzNDAzN2M1OGMwMmI2YmQ5ODk4ZmVlZjE5ODQ1IiwiZXhwIjoxNTE2Mjk5OTU2LCJuYmYiOjE1MTYyOTk1OTZ9jVW0KWtOeaYV4V3372rSVosPQqlOsaOj6-Oew_Ompe9GZ932aQi6tcc7uXdaz9jmBgLh8mlIZWyW4rFcTnyLQzjjK3nSYWNxxvobQRntigD1lNFYFR7ev9nrYnLw7oTQ9DkuluduWDMcdHYfmImeVNDC93txA_njdmta45ZG0VBeG9lrxInXMdxWXqb_W-ogEaHYbkfugXwlim7V1c38Wl8QR9QVNImFACzmdma_HBILmUDK9f4XdTA93TnB-WYhesJ_tvdmzrScMIFKANvNNT3smxec6ST-j1uCUBCQrVNxILapXiUrJER4aMmAbFweWs9bbgfhR9_sQVQDmLbVw" } ``` | Parameter | Description | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `access_token` | The access token issued by the Authorization Server. | | `token_type` | Provides the client with the information required to successfully utilize the access token to make a protected resource request. | | `expires_in` | The lifetime in seconds of the access token. 3600 / 1 hour is expected | | `refresh_token` | The refresh token, which can be used to [obtain new access tokens][2].
The refresh token is a long-lived JWT token that can be re-used.
It is coupled to an end-users consent and is valid as long as the application authorization record (consent) exists. Tenants can revoke authorizations. | | `id_token` | JSON Web Token or JWT, which consists of a Header, Payload, and Signature. The claims in the token form part of the payload. | The application now has an access token and can start making API requests to the SuperOffice tenant web services. Certified OpenID Connect libraries automatically verify the id\_token. If your application doesn't use a certified library, read [how to validate the id\_token JWT][3]. With a verified id\_token the application can safely store the `refresh_token` for fetching a new access token when the current expires. The Authorization Code flow is complete! ## Refresh token When an access token has expired, refresh tokens are used to get a new access tokens without forcing the user to go through the Authorization Core flow again. No other flow, only the Authorization Code flow, returns a refresh token. The refresh token is only used: * when the access (or ID) token has expired * when there is a need to update the claims in an ID token Refresh tokens must never be stored client-side in the browser! This is a long-lived token that is a contract between an application and tenant user. It 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 Refresh tokens may be **revoked** if we suspect its security has been compromised, or a customer or application vendor requests it be revoked. ### Send a refresh\_token request A `refresh_token` is used in a POST request sent to the tokens endpoint. ```http theme={null} 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=nKHwerkjh3asd6QShsnGKk4casdwCv3XtJu9PW2XasdtUMygLdI57BJjwCU0& redirect_url=http://localhost/callback Accept: application/json ``` **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 URL of your app, where authentication responses are sent and received by your app.
It must exactly match one of the redirect URLs registered with SuperOffice. | | `scope` | no | SuperOffice only supports the scope `openid` and is implicit for each flow. | ### Receive a refresh\_token response The response contains the token type, access token, expiration in seconds, and id token. ```http theme={null} { "token_type": "Bearer", "access_token": "8A:Cust12345.AZuHwfgrDEMONSTRATION_ONLYsdfswerwe3z5BnSYUSk4U4sdfr1Bjzycu0S1NC+xvghQ4VoUz9r6xpF2YAOCj0rb3LWnjLqllp3fYk8h2sxwc8d+5nb5bzGvHLHJ1UIRk38Ye4dPpmLSr4B8UaYNc9gs4Wgfgxqtii+o5w5XTYhPFW1rTcqbXbsnAtv8S+tJWHGPDxi2T/XUHpZxaDp2FT50nVePNiT9tAfP9QQwH0hbXN6RZzKfOcX37DtGcigMLsoc1qM+bJ8oWJqhVbPQIQ4J7**DEMONSTRATION_ONLY16y62E5hhs0e+ePThKSS7h52iaq5cwQMj0u2EAInK80UUjRTTpwznJWSlCFXsOD+cSNC6livOOz54PJoejKS+VxRqsr3TYQK+DEMONSTRATION_ONLYYIZr7fvFnvuTvGJTRSvOR2TuZhy2wl6/qOTLSpG9gvtPD2zjC+BiVmMW/P4Qhv3DWoSFCVqyQISqtFXy3rGexPIL+dz7kutoSkDYhcAl6aO8B0kdYKSsPow+8Jo8N3SD453r9uTGGiAl1tVWXfHo53eDEMONSTRATION_ONLYqCybSS9hF2sb5+v2HF36RPpt6bqOuCEIMAcpYJkiQ87kLTqsEGA9AA43sf1RfcB7lbVaVLFGmjUj1jgtIzVKiAR9eyMiWXL3dWMg+WM2Y0MOTsUrSb10kXkJ4g3M4TvH3rV4HTK3ohToxUleYvFbarx/8jeO7oLJfn3nth8NGtd1lJ", "expires_in": 3600, "id_token": "eyJ0eFor_Demonstration_PurposeszI1NiIsIng1dCI6IkZyZjdqRC1hc0dpRnFBREdUbVRKZkVxMTZZdyJ9.For_Demonstration_PurposesbSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9hc3NvY2lhdGVpZCI6IjUiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvaWRlbnRpdHlwcm92aWRlciI6ImNlbnRyYWwtc3VwZXJpZCIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9lbWFpbCI6InRvbnlAc3VwZXJvZmZpY2UuY29tIiwiaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubDEMONSTRATION_ONLYaHR0cDovL3NjaGVtZXMuc3VwZXJvZmZpY2UubmV0L2lkZW50aXR5L2N0eCI6IkN1c3QyNjc1OSIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9pc19hZG1pbmlzdHJhdG9yIjoiRmFsc2UiLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvc2VyaWFsIjoiMTgwMTU1MDE5MyIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9uZXRzZXJ2ZXJfdXJsIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tL0N1c3QyNjc1OS9SZW1vdGUvU2VydmljZXM4Ni8iLCJodHRwOi8vc2NoZW1lcy5zdXBlcm9mZmljZS5uZXQvaWRlbnRpdHkvd2ViYXBpX3VybCI6Imh0dHBzOi8vc29kLnN1cGVyb2ZmaWNlLmNvbS9DdXN0MjY3NTkvYXBpLyIsImh0dHA6Ly9zY2hlbWVzLnN1cGVyb2ZmaWNlLm5ldC9pZGVudGl0eS9zeXN0ZW1fdG9rZW4iOiJTdXDEMONSTRATION_ONLYTm9kZSBPSURDLThrOFE3RG1CZ28iLCJpYXQiOiIxNTQ2NjEzMTk4IiwiaXNzIjoiaHR0cHM6Ly9zb2Quc3VwZXJvZmZpY2UuY29tIiwiYXVkIjoiNmNmMjUzNzY2MTYzNDNiMzhkMTRkZGNkODA0ZjI4OTEiLCJleHAiOjE1NDY2MTM0OTgsIm5iZiI6MTU0NjYxMzEzOH0.ZzeDsNHJr86pLyqvpPQ5rMzRGd88Fh_RHLdBuG8fBmk_iZnFI5zaARDsTQffEzM30l61rZVmmpQo7KfAN6w27QB6XawURYwye59Z5c3fWRg8BJ4K5Uwik3PxtDEMONSTRATION_ONLYCQBG0D8I1jF2YZrI8ZO33PtRPisYHJ1F2F5O-qStzCXqhSjd1u7FjsJhqr1xGLDqLzkOm9_0v0nWFHESjBuPhFPIdt6lmcCuy48HGg5G0eM1_3h6SESsukXe0hNMqp3ZHjm5dCEoxE4HziLWSdRZIUa6tkP6wfHDHU_XUJu7PHo8Wx5aG9IBPZ_r1Xd8mgmt6g" } ``` [1]: ../index [2]: ../api [3]: ../validate-security-tokens [5]: https://tools.ietf.org/html/rfc7636 ## Related topics - [OICD Hybrid flow](/en/api/authentication/online/sign-in-user/hybrid-flow.md) - [Which flow should you use?](/en/api/authentication/online/which-flow-to-use.md) - [OICD Implicit flow](/en/api/authentication/online/sign-in-user/implicit-flow.md) - [OpenID Connect](/en/api/authentication/online/api.md) - [User contexts](/en/developer-portal/getting-started/user-contexts.md) - [Validating security tokens](/en/api/authentication/online/validate-security-tokens.md)