> ## Documentation Index > Fetch the complete documentation index at: https://docs-staging.auth0-mintlify.app/llms.txt > Use this file to discover all available pages before exploring further. > API and Mobile Configuration for the Mobile + API architecture scenario # API and Mobile Configuration (Mobile Apps + API) export const AuthCodeGroup = ({children, dropdown}) => { const [processedChildren, setProcessedChildren] = useState(children); useEffect(() => { let unsubscribe = null; function init() { unsubscribe = window.autorun(() => { const processChildren = node => { if (typeof node === "string") { let processedNode = node; for (const [key, value] of window.rootStore.variableStore.values.entries()) { const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`); processedNode = processedNode.replaceAll(new RegExp(escapedKey, "g"), value); } return processedNode; } else if (Array.isArray(node)) { return node.map(processChildren); } else if (node && node.props && node.props.children) { return { ...node, props: { ...node.props, children: processChildren(node.props.children) } }; } return node; }; setProcessedChildren(processChildren(children)); }); } if (window.rootStore) { init(); } else { window.addEventListener("adu:storeReady", init); } return () => { window.removeEventListener("adu:storeReady", init); unsubscribe?.(); }; }, [children]); return {processedChildren}; }; export const AuthCodeBlock = ({filename, icon, language, highlight, children}) => { const [displayText, setDisplayText] = useState(children); const [copyText, setCopyText] = useState(children); const wrapperRef = React.useRef(null); useEffect(() => { let unsubscribe = null; function init() { if (!window.autorun || !window.rootStore) { return; } unsubscribe = window.autorun(() => { let processedChildrenForDisplay = children; let processedChildrenForCopy = children; for (const [key, value] of window.rootStore.variableStore.values.entries()) { const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`); let displayValue = value; if (key === "{yourClientSecret}" && value !== "{yourClientSecret}") { displayValue = value.substring(0, 3) + "*****MASKED*****"; } processedChildrenForDisplay = processedChildrenForDisplay.replaceAll(new RegExp(escapedKey, "g"), displayValue); processedChildrenForCopy = processedChildrenForCopy.replaceAll(new RegExp(escapedKey, "g"), value); } setDisplayText(processedChildrenForDisplay); setCopyText(processedChildrenForCopy); }); } if (window.rootStore) { init(); } else { window.addEventListener("adu:storeReady", init); } return () => { window.removeEventListener("adu:storeReady", init); unsubscribe?.(); }; }, [children]); useEffect(() => { if (!wrapperRef.current) return; const originalWriteText = navigator.clipboard.writeText.bind(navigator.clipboard); let isOverriding = false; const handleClick = e => { const button = e.target.closest('[data-testid="copy-code-button"]'); if (!button || !wrapperRef.current.contains(button)) return; isOverriding = true; navigator.clipboard.writeText = text => { if (isOverriding) { isOverriding = false; navigator.clipboard.writeText = originalWriteText; return originalWriteText(copyText); } return originalWriteText(text); }; setTimeout(() => { if (isOverriding) { isOverriding = false; navigator.clipboard.writeText = originalWriteText; } }, 100); }; const wrapper = wrapperRef.current; wrapper.addEventListener('click', handleClick, true); return () => { wrapper.removeEventListener('click', handleClick, true); if (navigator.clipboard.writeText !== originalWriteText) { navigator.clipboard.writeText = originalWriteText; } }; }, [copyText]); return
{displayText}
; }; In this section we will see how we can implement an API for our scenario. For simplicity, we will keep our implementation solely focused on authentication and authorization. As you will see in the samples, the input timesheet entry will be hard-coded, and the API will not persist the timesheet entry. Instead, it will simply echo back some of the info. ## Define the API endpoints First we need to define the endpoints of our API. An **API endpoint** is a unique URL that represents an object. To interact with this object, you need to point your application to its URL. For example, if you had an API that could return either orders or customers, you might configure two endpoints: `/orders` and `/customers`. Your application would interact with these endpoints using different HTTP methods; for example, `POST /orders` could create a new order or `GET /orders` could retrieve the dataset of one or more orders. For this implementation we will only define two endpoints; one for retrieving a list of all timesheets for an employee, and another which will allow an employee to create a new timesheet entry. An `HTTP GET` request to the `/timesheets` endpoint will allow a user to retrieve their timesheets, and an `HTTP POST` request to the `/timesheets` endpoint will allow a user to add a new timesheet. See the implementation in [Node.js](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs#1-define-the-api-endpoints) ### Secure the Endpoints When an API receives a request with a bearer Access Token as part of the header, the first thing to do is to validate the token. This consists of a series of steps, and if any of these fails then the request must be rejected with a `Missing or invalid token` error message to the calling app. The validations that the API should perform are: * Check that the JWT is well formed * Check the signature * Validate the standard claims [JWT.io](https://jwt.io/) provides a list of libraries that can do most of the work for you: parse the JWT, verify the signature and the claims. Part of the validation process is to also check the Client permissions (scopes), but we will address this separately in the next paragraph of this document. For more information on validating Access Tokens, see [Validate Access Tokens](/docs/secure/tokens/access-tokens/validate-access-tokens). See the implementation in [Node.js](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs#2-secure-the-api-endpoints) ### Check the Client's Permissions By now we have verified that the JWT is valid. The last step is to verify that the client has the permissions required to access the protected resources. To do so, the API needs to check the [scopes](/docs/get-started/apis/scopes) of the decoded JWT. This claim is part of the payload and it is a space-separated list of strings. See the implementation in [Node.js](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs#3-check-the-client-permissions) ### Determine user identity For both endpoints (retrieving the list of timesheets, and adding a new timesheet) we will need to determine the identity of the user. For retrieving the list of timesheets this is to ensure that we only return the timesheets belonging to the user making the request, and for adding a new timesheet this is to ensure that the timesheet is associated with the user making the request. One of the standard JWT claims is the `sub` claim which identifies the principal that is the subject to the claim. In the case of the Implicit Grant flow this claim will contain the user's identity, which will be the unique identifier for the Auth0 user. You can use this to associate any information in external systems with a particular user. You can also use a custom claim to add another attribute of the user - such as their email address - to the Access Token and use that to uniquely identify the user. See the implementation in [Node.js](/docs/get-started/architecture-scenarios/mobile-api/api-implementation-nodejs#4-determine-the-user-identity) ## Implement the Mobile App In this section we will see how we can implement a mobile application for our scenario. [See the implementation in Android.](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#1-set-up-the-application) ### Authorize the User To authorize the user we will implement the [Authorization Code Flow with Proof Key for Code Exchange (PKCE)](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce). The mobile application should first send the user to the [authorization URL](https://auth0.com/docs/api/authentication#authorization-code-grant-pkce-) along with the `code_challenge` and the method used to generate it: export const codeExample1 = `https://{yourDomain}/authorize? audience=API_AUDIENCE& scope=SCOPE& response_type=code& client_id={yourClientId}& code_challenge=CODE_CHALLENGE& code_challenge_method=S256& redirect_uri=https://YOUR_APP/callback`; The `GET` request to the authorization URL should include the following values: | Parameter | Description | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **client\_id** | The value of your Auth0 Client Id. You can retrieve it from the Settings of your Application at the [Auth0 Dashboard](https://manage.auth0.com/#/applications). | | **audience** | The value of your API Identifier. You can retrieve it from the Settings of your API at the [Auth0 Dashboard](https://manage.auth0.com/#/apis). | | **scope** | The [scopes](/docs/get-started/apis/scopes) which determine the claims to be returned in the ID Token and Access Token. For example, a scope of `openid` will return an ID Token in the response. In our example mobile app, we use the following scopes: `create:timesheets read:timesheets openid profile email offline_access`. These scopes allow the mobile app to call the API, obtain a [Refresh Token](/docs/glossary?term=Refresh+Token), and return the user's `name`, `picture`, and `email` claims in the ID Token. | | **response\_type** | Indicates the Authentication Flow to use. For a mobile application using PKCE, this should be set to `code`. | | **code\_challenge** | The generated code challenge from the code verifier. You can find instructions on generating a code challenge [here](/docs/get-started/authentication-and-authorization-flow/authorization-code-flow-with-pkce/call-your-api-using-the-authorization-code-flow-with-pkce#authorize-the-user%23create-a-code-verifier). | | **code\_challenge\_method** | Method used to generate the challenge. Auth0 supports only `S256`. | | **redirect\_uri** | The URL which Auth0 will redirect the browser to after authorization has been granted by the user. The Authorization Code will be available in the code URL parameter. This URL must be specified as a valid callback URL under your [Application's Settings](https://manage.auth0.com/#/applications). | [See the implementation in Android.](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#2-authorize-the-user) ### Get the Credentials After a successful request to the authorization URL, you should receive the following response: export const codeExample2 = `HTTP/1.1 302 Found Location: https://{yourDomain}/callback?code=AUTHORIZATION_CODE`; Next you can exchange the `authorization_code` from the response for an Access Token that can be used to call your API. Perform a `POST` request to the [Token URL](https://auth0.com/docs/api/authentication#authorization-code-pkce-) including the following data: ```bash cURL theme={null} curl --request POST \ --url 'https://{yourDomain}/oauth/token' \ --header 'content-type: application/x-www-form-urlencoded' \ --data grant_type=authorization_code \ --data 'client_id={yourClientId}' \ --data code_verified=YOUR_GENERATED_CODE_VERIFIER \ --data code=YOUR_AUTHORIZATION_CODE \ --data 'redirect_uri=https://{https://yourApp/callback}' ``` ```csharp C# theme={null} var client = new RestClient("https://{yourDomain}/oauth/token"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/x-www-form-urlencoded"); request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```go Go theme={null} package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://{yourDomain}/oauth/token" payload := strings.NewReader("grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("content-type", "application/x-www-form-urlencoded") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```java Java theme={null} HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token") .header("content-type", "application/x-www-form-urlencoded") .body("grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}") .asString(); ``` ```javascript Node.JS theme={null} var axios = require("axios").default; var options = { method: 'POST', url: 'https://{yourDomain}/oauth/token', headers: {'content-type': 'application/x-www-form-urlencoded'}, data: new URLSearchParams({ grant_type: 'authorization_code', client_id: '{yourClientId}', code_verified: 'YOUR_GENERATED_CODE_VERIFIER', code: 'YOUR_AUTHORIZATION_CODE', redirect_uri: 'https://{https://yourApp/callback}' }) }; axios.request(options).then(function (response) { console.log(response.data); }).catch(function (error) { console.error(error); }); ``` ```php PHP theme={null} $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://{yourDomain}/oauth/token", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_POSTFIELDS => "grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}", CURLOPT_HTTPHEADER => [ "content-type: application/x-www-form-urlencoded" ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ``` ```python Python theme={null} import http.client conn = http.client.HTTPSConnection("") payload = "grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}" headers = { 'content-type': "application/x-www-form-urlencoded" } conn.request("POST", "/{yourDomain}/oauth/token", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` ```ruby Ruby theme={null} require 'uri' require 'net/http' require 'openssl' url = URI("https://{yourDomain}/oauth/token") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE request = Net::HTTP::Post.new(url) request["content-type"] = 'application/x-www-form-urlencoded' request.body = "grant_type=authorization_code&client_id={yourClientId}&code_verified=YOUR_GENERATED_CODE_VERIFIER&code=YOUR_AUTHORIZATION_CODE&redirect_uri=https%3A%2F%2F{https://yourApp/callback}" response = http.request(request) puts response.read_body ``` | Parameter | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **grant\_type** | This must be set to `authorization_code`. | | **client\_id** | The value of your Auth0 Client Id. You can retrieve it from the Settings of your Application at the [Auth0 Dashboard](https://manage.auth0.com/#/applications). | | **code\_verifier** | Cryptographically random key that was used to generate the `code_challenge` passed to [authorization URL](https://auth0.com/docs/api/authentication#authorization-code-grant-pkce-) (`/authorize`). | | **code** | The `authorization_code` received from the previous authorize call. | | **redirect\_uri** | The URL must match the `redirect_uri` passed in the previous section to `/authorize`. | The response from the Token URL will contain: ```json lines theme={null} { "access_token": "eyJz93a...k4laUWw", "refresh_token": "GEbRxBN...edjnXbL", "id_token": "eyJ0XAi...4faeEoQ", "token_type": "Bearer", "expires_in":86400 } ``` * **access\_token**: An Access Token for the API, specified by the `audience`. * **refresh\_token**: A [Refresh Token](/docs/secure/tokens/refresh-tokens) will only be present if you included the `offline_access` scope AND enabled **Allow Offline Access** for your API in the Dashboard. * **id\_token**: An ID Token JWT containing user profile information. * **token\_type**: A string containing the type of token, this will always be a Bearer token. * **expires\_in**: The amount of seconds until the Access Token expires. You will need to store the above credentials in local storage for use in calling your API and retrieving the user profile. [See the implementation in Android](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#store-credentials). ### Get the User Profile To retrieve the [User Profile](https://auth0.com/docs/api/authentication?http#user-profile), your mobile application can decode the [ID Token](/docs/secure/tokens/id-tokens) using one of the [JWT libraries](https://jwt.io/#libraries-io). This is done by [verifying the signature](/docs/secure/tokens/id-tokens/validate-id-tokens#verify-the-signature) and [verifying the claims](/docs/secure/tokens/id-tokens/validate-id-tokens#verify-the-claims) of the token. After validating the ID Token, you can access its payload containing the user information: ```json lines theme={null} { "email_verified": false, "email": "test.account@userinfo.com", "clientID": "q2hnj2iu...", "updated_at": "2016-12-05T15:15:40.545Z", "name": "test.account@userinfo.com", "picture": "https://s.gravatar.com/avatar/dummy.png", "user_id": "auth0|58454...", "nickname": "test.account", "created_at": "2016-12-05T11:16:59.640Z", "sub": "auth0|58454..." } ``` [See the implementation in Android.](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#3-get-the-user-profile) ### Display UI Elements Conditionally Based on Scope Based on the `scope` of the user, you may want to show or hide certain UI elements. To determine the scope issued to a user, you will need to inspect the `scope` which was granted when the user was authenticated. This will be a string containing all the scopes, so you therefore need to inspect this string to see whether it contains the required `scope` and based on that make a decision whether to display a particular UI element. [See the implementation in Android](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#4-display-ui-elements-conditionally-based-on-scope) ### Call the API To access secured resources from your API, the authenticated user's Access Token needs to be included in requests that are sent to it. This is accomplished by sending the Access Token in an `Authorization` header using the `Bearer` scheme. [See the implementation in Android.](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#5-call-the-api) ### Renew the Token Refresh Tokens must be stored securely by an application since they do not expire and allow a user to remain authenticated essentially forever. If Refresh Tokens are compromised or you no longer need them, you can revoke the Refresh Tokens using the [Authentication API](https://auth0.com/docs/api/authentication#revoke-refresh-token). To refresh your Access Token, perform a `POST` request to the `/oauth/token` endpoint using the Refresh Token from your authorization result. A [Refresh Token](/docs/secure/tokens/refresh-tokens) will only be present if you included the `offline_access` scope in the previous authorization request and enabled **Allow Offline Access** for your API in the Dashboard. Your request should include: ```bash cURL theme={null} curl --request POST \ --url 'https://{yourDomain}/oauth/token' \ --header 'content-type: application/x-www-form-urlencoded' ``` ```csharp C# theme={null} var client = new RestClient("https://{yourDomain}/oauth/token"); var request = new RestRequest(Method.POST); request.AddHeader("content-type", "application/x-www-form-urlencoded"); IRestResponse response = client.Execute(request); ``` ```go Go theme={null} package main import ( "fmt" "net/http" "io/ioutil" ) func main() { url := "https://{yourDomain}/oauth/token" req, _ := http.NewRequest("POST", url, nil) req.Header.Add("content-type", "application/x-www-form-urlencoded") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```java Java theme={null} HttpResponse response = Unirest.post("https://{yourDomain}/oauth/token") .header("content-type", "application/x-www-form-urlencoded") .asString(); ``` ```javascript Node.JS theme={null} var axios = require("axios").default; var options = { method: 'POST', url: 'https://{yourDomain}/oauth/token', headers: {'content-type': 'application/x-www-form-urlencoded'} }; axios.request(options).then(function (response) { console.log(response.data); }).catch(function (error) { console.error(error); }); ``` ```php PHP theme={null} $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://{yourDomain}/oauth/token", CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => "", CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 30, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_HTTPHEADER => [ "content-type: application/x-www-form-urlencoded" ], ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { echo "cURL Error #:" . $err; } else { echo $response; } ``` ```python Python theme={null} import http.client conn = http.client.HTTPSConnection("") headers = { 'content-type': "application/x-www-form-urlencoded" } conn.request("POST", "/{yourDomain}/oauth/token", headers=headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` ```ruby Ruby theme={null} require 'uri' require 'net/http' require 'openssl' url = URI("https://{yourDomain}/oauth/token") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true http.verify_mode = OpenSSL::SSL::VERIFY_NONE request = Net::HTTP::Post.new(url) request["content-type"] = 'application/x-www-form-urlencoded' response = http.request(request) puts response.read_body ``` | Parameter | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **grant\_type** | This must be set to `refresh_token`. | | **client\_id** | The value of your Auth0 Client Id. You can retrieve it from the Settings of your Application at the [Auth0 Dashboard](https://manage.auth0.com/#/applications). | | **refresh\_token** | the Refresh Token to use, from the previous authentication result. | The response will include the new Access Token: ```json lines theme={null} { "access_token": "eyJz93a...k4laUWw", "refresh_token": "GEbRxBN...edjnXbL", "id_token": "eyJ0XAi...4faeEoQ", "token_type": "Bearer", "expires_in":86400 } ``` [See the implementation in Android.](/docs/get-started/architecture-scenarios/mobile-api/mobile-implementation-android#store-the-credentials)