|
| 1 | +--- |
| 2 | +title: Set Up an API |
| 3 | +description: Learn how to set up an API in Auth0 Dashboard. |
| 4 | +topics: |
| 5 | + - apis |
| 6 | +contentType: how-to |
| 7 | +useCase: |
| 8 | + - set-up-api |
| 9 | + - get-started |
| 10 | +--- |
| 11 | +# Set Up an API |
| 12 | + |
| 13 | +1. Click on the [APIs menu option](${manage_url}/#/apis) on the left. |
| 14 | + |
| 15 | + ::: note |
| 16 | + The API tab will already have one API created automatically, the **Auth0 Management API**. For more details on the features of the Management API and its available endpoints, refer to: [Management API](/api/management/v2). |
| 17 | + ::: |
| 18 | + |
| 19 | +2. Click the **+ Create API** button. |
| 20 | + |
| 21 | +  |
| 22 | + |
| 23 | + You need to provide the following information for your API: |
| 24 | + |
| 25 | + - **Name**: a friendly name for the API. Does not affect any functionality. |
| 26 | + |
| 27 | + - **Identifier**: a unique identifier for the API. Auth0 recommends using a URL. Auth0 does differentiate between URLs that include the last forward slash. For example, https://example.com and https://example.com/ are two different identifiers. The URL does not have to be a publicly available URL. Auth0 will not call your API. This value **cannot** be modified afterwards. |
| 28 | + |
| 29 | + - **Signing Algorithm**: the algorithm to sign the tokens with. The available values are `HS256` and `RS256`. When selecting `RS256` the token will be signed with the tenant's private key. For more details on the signing algorithms go to the [Signing Algorithms paragraph](#signing-algorithms). |
| 30 | + |
| 31 | +3. Fill in the required information and click the **Create** button. |
| 32 | + |
| 33 | + Once you do so you will be navigated to the *Quick Start* of your API. Here you can find details on the implementation changes you have to do to your API, which basically consists of choosing a JWT library from a predefined list and configuring this library to validate the Access Tokens in your API. |
| 34 | + |
| 35 | +  |
| 36 | + |
| 37 | + The other available views for your API are: |
| 38 | + |
| 39 | + - **Settings**: lists the settings for your API. Some are editable. Here you can change the token expiration time and enable offline access (this way Auth0 will allow your applications to ask for <dfn data-key="refresh-token">Refresh Tokens</dfn> for this API). For details refer to the [API Settings paragraph](#api-settings). |
| 40 | + |
| 41 | + - **Scopes**: here you can define the scopes for this API, by setting a name and a description. |
| 42 | + |
| 43 | + - **Machine to Machine Applications**: lists all applications for which the **Client Credentials** grant is **enabled**. By default, this grant is **enabled* for [Regular Web Applications and Machine to Machine Applications](/applications/concepts/app-types-auth0). You can authorize any of these applications to request Access Tokens for your API. Optionally, you can select a subset of the defined scopes to limit your authorized application's access. |
| 44 | + |
| 45 | + - **Test**: from this view, you can execute a sample Client Credentials flow with any of your authorized applications to check that everything is working as expected. |
| 46 | + |
| 47 | +## API settings |
| 48 | + |
| 49 | +Click on the **Settings** tab of your [API](${manage_url}/#/apis) to review the available settings: |
| 50 | + |
| 51 | +- **Id**: A unique alphanumeric string generated by Auth0. The information is read only and you will only need it if you will be working directly with [Auth0's Management API Resource Servers endpoints](/api/management/v2#!/Resource_Servers/get_resource_servers_by_id). |
| 52 | + |
| 53 | +- **Name**: A friendly name for the API. Does not affect any functionality. The following characters are not allowed: `< >`. |
| 54 | + |
| 55 | +- **Identifier**: A unique identifier for your API. This value is set upon API creation and cannot be modified afterwards. We recommend using a URL but note that this doesn't have to be a publicly available URL, Auth0 will not call your API at all. |
| 56 | + |
| 57 | +- **Token Expiration (Seconds)**: The amount of time (in seconds) before the Auth0 Access Token expires. The default value is 86400 seconds (24 hours). The maximum value you can set is 2592000 seconds (30 days). |
| 58 | + |
| 59 | +- **Allow Skipping User Consent**: When a first party application requests authorized access against an API with the *Allow Skipping User Consent* flag set, the User Consent dialog will not be shown to the final user. Note that if the hostname of your application's <dfn data-key="callback">**callback URL**</dfn> is `localhost` or `127.0.0.1` the consent dialog will always be displayed. |
| 60 | + |
| 61 | +- **Allow Offline Access**: If this setting is enabled, Auth0 will allow applications to ask for Refresh Tokens for this API. |
| 62 | + |
| 63 | +- **Signing Algorithm**: The algorithm to sign the tokens with. The available values are `HS256` and `RS256`. When selecting `RS256` (recommended) the token will be signed with the tenant's private key. This value is set upon API creation and cannot be modified afterwards. For more details on the signing algorithms see the [Signing Algorithms paragraph](#signing-algorithms) below. |
| 64 | + |
| 65 | +## Signing algorithms |
| 66 | + |
| 67 | +When you create an API you have to select the algorithm your tokens will be signed with. The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way. |
| 68 | + |
| 69 | +::: note |
| 70 | +The signature is part of a JWT. If you are not familiar with the JWT structure, please see [JSON Web Tokens (JWTs) in Auth0](/jwt#what-is-the-json-web-token-structure-). |
| 71 | +::: |
| 72 | + |
| 73 | +To create the signature part you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that. That algorithm, which is part of the JWT header, is the one you select for your API: `HS256` or `RS256`. |
| 74 | + |
| 75 | +- **RS256** is an [asymmetric algorithm](https://en.wikipedia.org/wiki/Public-key_cryptography) which means that there are two keys: one public and one private (secret). Auth0 has the secret key, which is used to generate the signature, and the consumer of the JWT has the public key, which is used to validate the signature. |
| 76 | + |
| 77 | +- **HS256** is a [symmetric algorithm](https://en.wikipedia.org/wiki/Symmetric-key_algorithm) which means that there is only one secret key, shared between the two parties. The same key is used both to generate the signature and to validate it. Special care should be taken in order for the key to remain confidential. |
| 78 | + |
| 79 | +The most secure practice, and our recommendation, is to use **RS256**. Some of the reasons are: |
| 80 | + |
| 81 | +- With RS256 you are sure that only the holder of the private key (Auth0) can sign tokens, while anyone can check if the token is valid using the public key. |
| 82 | + |
| 83 | +- Under HS256, if the secret key is compromised (e.g. by the application) you would have to re-deploy the API with the new secret. |
| 84 | + |
| 85 | +- With RS256 you can request a token that is valid for multiple <dfn data-key="audience">audiences</dfn>. |
| 86 | + |
| 87 | +- With RS256 you can implement key rotation without having to re-deploy the API with the new secret. |
| 88 | + |
| 89 | +::: panel Verify an RS256 signed token |
| 90 | +Go to [Dashboard > Applications](${manage_url}/#/applications). Open the **Settings** of your applications, scroll down and open **Advanced Settings**. Open the **Certificates** tab and you will find the Public Key in the **Signing Certificate** field. |
| 91 | + |
| 92 | +If you want to use the Public Key to verify a JWT signature on [JWT.io](https://jwt.io/), you can copy the Public Key and paste it in the **Public Key or Certificate** field under the **Verify Signature** section on the [JWT.io](https://jwt.io/) website. |
| 93 | + |
| 94 | +If you want to verify the signature of a token from one of your applications, we recommend that you get the Public Key from your tenant's [JSON Web Key Set (JWKS)](/jwks). Your tenant's JWKS is `https://${account.namespace}/.well-known/jwks.json`. |
| 95 | +::: |
| 96 | + |
| 97 | +For a more detailed overview of the JWT signing algorithms, see [JSON Web Token (JWT) Signing Algorithms Overview](https://auth0.com/blog/json-web-token-signing-algorithms-overview/). |
| 98 | + |
| 99 | +# Keep reading |
| 100 | + |
| 101 | +- [API Authorization Overview](/api-auth) |
| 102 | +- [Which OAuth Flow to Use](/api-auth/which-oauth-flow-to-use) |
| 103 | +- [Why you should always use Access Tokens to secure an API](/api-auth/why-use-access-tokens-to-secure-apis) |
0 commit comments