---
updatedAt: 2025-06-23T09:05:21.000Z
agentTools:
  projectIndex: https://docs.rapidapi.com/v2.0/llms.txt
---

# Configuring API Authorization (legacy)

Configure additional API authorization (or authentication) mechanisms used by your API.

## Authorization overview

By default, when you add an API to the Hub and use the RapidAPI Proxy, authorization called **RapidAPI Auth** is used. This is the simplest form of authorization for consumers of the API, and the other types of authorization described here can be "added on" to this default authorization. If the API requires additional authorization such as OAuth 2, it is up to the API provider to configure that additional authorization, as described below.

<Image alt="Authorization options for APIs listed on the Hub." align="center" border={true} src="https://files.readme.io/e3a3a46-hub-listing-authorization.png">
  Authorization options for APIs listed on the Hub.
</Image>

With RapidAPI Auth, headers named **X-RapidAPI-Host** and **X-RapidAPI-Key** must be sent with each API request. The value of the **X-RapidAPI-Host** header uniquely identifies the API being called, and is defined by Rapid. The value of the **X-RapidAPI-Key** header corresponds to an app key. These apps and keys can be found in the [Developer Dashboard](https://docs.rapidapi.com/v2.0/docs/developer-dashboard) (Apps). The values of these headers are automatically populated for you when testing an endpoint by selecting the correct context from the team/personal context (shown below). If the context has multiple apps, you can select the app from the **RapidAPI App** dropdown (shown below). The values of these headers are also automatically added to the sample code.

If the header information is incorrect, API calls will receive a 4xx client error response.

<Image alt="Viewing RapidAPI Auth headers in the API's listing." align="center" border={true} src="https://files.readme.io/44ec41d-api-listing-rapidapi-auth.png">
  Viewing RapidAPI Auth headers in the API's listing.
</Image>

RapidAPI Auth has multiple purposes. The RapidAPI Auth header values must be valid for API calls to be successfully made via the RapidAPI Proxy. In addition, these values are used to track usage and billing data, and to rate-limit requests (if necessary). If you are using the RapidAPI Proxy, you must pass valid RapidAPI Auth headers, even if you choose additional forms of authorization, as described below.

> 📘 Not using the RapidAPI Proxy
>
> If your API [does not use the RapidAPI Proxy](https://docs.rapidapi.com/v2.0/docs/gateway-configuration), the RapidAPI Auth described above is not used. This is because calls to the API's endpoints are made directly to the API itself. In this case, the **X-RapidAPI-Host** and **X-RapidAPI-Key** header parameters are not used, since only the RapidAPI Proxy understands their meaning.
>
> The other types of authorization described below can still be used with the API, assuming the API itself uses some form of authorization. Choosing one of these authorization methods has the effect of changing the API consumer experience when testing the API via the API Hub, and helps provide accurate sample code.

The additional forms of authorization described below are used if the API itself requires authentication and/or authorization. Choosing one of these authorization methods has the effect of changing the API consumer experience when testing the API, and helps provide accurate sample code. For example, if the API uses basic authentication, the user interface will prompt the user to authenticate while testing the API.

In addition to RapidAPI Auth, you can require these other forms of authorization for your API:

* [OAuth2](#add-oauth2-authentication)
* [Header](#add-header-authentication)
* [Query](#add-header-authentication)
* [Basic](#add-basic-authentication)
* [Bearer](#add-bearer-authentication)

These are set using the **Hub Listing > Access Control > Authorization** radio buttons, as shown in the top screenshot above.

## Why add other forms of authorization for an API?

API providers configure an additional form of authorization because the API itself has authorizations requirements, possibly from an API gateway. If these additional authorization requirements are not accounted for, API consumers will not be able to successfully test the API's endpoints using the API Hub - they will receive permission-related responses such as **403 Forbidden**. Also, the sample code provided will not include the additional authorization requirements, such as an **Authorization** header.

## Add OAuth2 authentication

[OAuth2](https://oauth.net/2/) is a token-based authorization protocol. Using this authorization method in Rapid, API providers can support APIs that use OAuth2 for security. OAuth2 is very flexible, supporting several authorization flows, or grant types. Additionally, depending on the user, API providers can authorize only certain capabilities, known as scopes, for their API. Therefore, compared to the other authorization methods, there are more options to configure here.

Rapid supports three OAuth grant types: Client credentials, authorization code, and password. These are the most likely grant types used with APIs. We will discuss these separately.

### Client credentials grant type

To enable client credentials OAuth2 authorization for your API:

1. Navigate to **Studio (My APIs)**.
2. In the sidebar, click the **Hub Listing** tab for your API.
3. Click the **Gateway** tab.
4. For **Access Control > Authorization**, select **OAuth2**.
5. For **Grant Type**, select **Client Credentials**.
6. For **Token URL**, enter the URL where calls are made to obtain a token for the API.
7. Check the **Token Client Handle** box if you would prefer that the token URL is called directly by the browser rather than via the RapidAPI Proxy. The token URL endpoint would then be responsible for handling CORS issues related to calling this URL from the browser via the rapidapi.com domain. See <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" target="_blank">this link</a> for more information.
8. For **Client Authentication**, select either **Header** or **Body**. This specifies whether Rapid should place the authentication data in the request's header or body. Consult your API's documentation to determine which approach is supported.
9. For **Separator**, select either **Space** or **Comma**. This separator setting is used if you specify more than one OAuth scope.
10. For **Header Prefix**, enter any prefix that is added to the Authorization header before the token. Some API gateways might require this value.
11. If your API supports scopes, under **Scopes**, add the scope names and optional descriptions. API consumers are then given the option of including these scopes in their requests. Scopes authorize the API consumer to perform certain actions.
12. Click **Save**.

<Image alt="Configuring OAuth2 Client Credentials grant type for an API." align="center" border={true} src="https://files.readme.io/caa40de-oauth2-client-credentials.png">
  Configuring OAuth2 client credentials grant type for an API.
</Image>

When an API consumer uses the API, they will have to provide a valid token to successfully call the API. When testing an endpoint, the developer sees a **Header Parameter** named Authorization OAUTH2.

<Image title="GetToken.png" alt={866} align="center" border={true} src="https://files.readme.io/1b18366-GetToken.png">
  OAuth2 authorization in the API listing.
</Image>

Clicking the **Get Token** button (above) opens an **OAuth2 Authentication** dialog (below), where the API consumer enters the **Client ID** and **Client Secret** needed to obtain a token. They can also check boxes for the scopes that they want to use when making API requests. Clicking **Authorize** will result in a token that can be used when calling the API.

> 📘 Auto-filling the Client ID and Client Secret using authorizations
>
> Enterprise customers can use [Authorizations](https://docs.rapidapi.com/v2.0/docs/configuring-api-authorization) to enable API consumers to obtain tokens without needing to know the Client ID or Client Secret.

<Image title="OAuthDialog.png" alt={1430} align="center" border={true} src="https://files.readme.io/c7c2937-OAuthDialog.png">
  The dialog that pops up when the API consumer clicks Get Token.
</Image>

> 📘 Client ID and Client Secret
>
> If your API consumers can receive access tokens without providing the Client ID and Client Secret as shown above, you have the option of using the **[Header](#add-header-authentication)** authentication set instead of OAuth2. The API provider can add an "authorization" header, and API consumers can add an access token directly when testing the API. This bypasses the Client ID and Client Secret workflow shown above.

### Authorization code grant type

To enable authorization code OAuth2 authorization for your API:

1. Navigate to **Studio (My APIs)**.
2. In the sidebar, click the **Hub Listing** tab for your API.
3. Click the **Gateway** tab.
4. For **Access Control > Authorization**, select **OAuth2**.
5. For **Grant Type**, select **Authorization Code**.
6. For **Authorization URL**, enter the URL (often ending in /oauth2/authorize) where calls are made to obtain an authorization code for the API. This code is needed before tokens can be obtained.
7. For **Token URL**, enter the URL (often ending in /oauth2/token) where calls are made to obtain a token for the API.
8. Check the **Token Client Handle** box if you would prefer that the token Authorization URL is called directly by the browser rather than via the RapidAPI Proxy. The Authorization URL endpoint would then be responsible for handling CORS issues related to calling this URL from the browser via the rapidapi.com domain. See <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" target="_blank">this link</a> for more information.
9. Check the **Client Secret** checkbox if your API consumers should be prompted for the client secret. Some APIs may not require client secrets.
10. For **Client Authentication**, select either **Header** or **Body**. This specifies whether RapidAPI should place the authentication data in the request's header or body. Consult your API's documentation to determine which approach is supported.
11. For **Separator**, select either **Space** or **Comma**. This separator setting is used if you specify more than one scope.
12. For **PKCE** (Proof Key for Code Exchange), enable the slider if your API requires a PKCE challenge. Then select the **Code Challenge Method** from the dropdown. The options are **S256** or **Plain**. For more information on PKCE, see <a href="https://oauth.net/2/pkce/" target="_blank">this page</a>.
13. For **Header Prefix**, enter any prefix that is added to the Authorization header before the token. Some API gateways might require this value.
14. If your API supports scopes, under **Scopes**, add the scope names and descriptions. API consumers are then given the option of including these scopes in their requests. Scopes authorize the API consumer to perform certain actions.
15. Click **Save**.

<Image alt="Configuring authorization code OAuth2 grant type." align="center" border={true} src="https://files.readme.io/eca3b34-oauth-authorization-code.png">
  Configuring authorization code OAuth2 grant type.
</Image>

When an API consumer uses the API, they will have to provide a valid token to successfully call the API. When testing an endpoint, the developer sees a **Header Parameter** named Authorization OAUTH2.

<Image title="GetToken.png" alt={866} align="center" border={true} src="https://files.readme.io/58e737d-GetToken.png">
  OAuth2 authorization in the API listing.
</Image>

Clicking the **Get Token** button (above) opens an **OAuth2 Authentication** dialog (below), where the API consumer enters the **Client ID** and **Client Secret** needed to obtain a token. They can also check boxes for the scopes that they want to use when making API requests. Clicking **Authorize** will result in a token that can be used when calling the API.

> 📘 Auto-filling the Client ID and Client Secret using authorizations
>
> Enterprise customers can use [Authorizations](https://docs.rapidapi.com/v2.0/docs/configuring-api-authorization) to enable API consumers to obtain tokens without needing to know the Client ID or Client Secret.

> 📘
>
> If your API is not configured to use a client secret, you can enter any value for **Client Secret**.

<Image title="AuthorizationCodeDialog.png" alt={1432} align="center" border={true} src="https://files.readme.io/eca8992-AuthorizationCodeDialog.png">
  The dialog that pops up when the API consumer clicks Get Token.
</Image>

> 📘 Client ID and Client Secret
>
> If your API consumers can receive access tokens without providing the Client ID and Client Secret as shown above, you have the option of using the **[Header](#add-header-authentication)** authentication set instead of OAuth2. The API provider can add an "authorization" header, and API consumers can add an access token directly when testing the API. This bypasses the Client ID and Client Secret workflow shown above.

### Password grant type

To enable password OAuth2 authentication for your API:

1. Navigate to **Studio (My APIs)**.
2. In the sidebar, click the **Hub Listing** tab for your API.
3. Click the **Gateway** tab.
4. For **Access Control > Authorization**, select **OAuth2**.
5. For **Grant Type**, select **Password**.
6. For **Token URL**, enter the URL where calls are made to obtain a token for the API.
7. Check the **Token Client Handle** box if you would prefer that the token URL is called directly by the browser rather than via the RapidAPI Proxy. The token URL endpoint would then be responsible for handling CORS issues related to calling this URL from the browser via the rapidapi.com domain. See <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" target="_blank">this link</a> for more information.
8. For **Client Authentication**, select either **Header** or **Body**. This specifies whether Rapid should place the authentication data in the request's header or body. Consult your API's documentation to determine which approach is supported.
9. For **Separator**, select either **Space** or **Comma**. This separator setting is used if you specify more than one OAuth scope.
10. For **Header Prefix**, enter any prefix that is added to the Authorization header before the token. Some API gateways might require this value.
11. If your API supports scopes, under **Scopes**, add the scope names and optional descriptions. API consumers are then given the option of including these scopes in their requests. Scopes authorize the API consumer to perform certain actions.
12. Click **Save**.

<Image alt="Configuring OAuth2 password grant type for an API." align="center" border={true} src="https://files.readme.io/56868b2-oauth2-password.png">
  Configuring OAuth2 password grant type for an API.
</Image>

When an API consumer uses the API, they will have to provide a valid token to successfully call the API. When testing an endpoint, the developer sees a **Header Parameter** named Authorization OAUTH2.

<Image title="GetToken.png" alt={866} align="center" border={true} src="https://files.readme.io/1b18366-GetToken.png">
  OAuth2 authorization in the API listing.
</Image>

Clicking the **Get Token** button (above) opens an **OAuth2 Authentication** dialog (below), where the API consumer enters the **Client ID** and **Client Secret** needed to obtain a token. They can also check boxes for the scopes that they want to use when making API requests. Clicking **Authorize** will result in a token that can be used when calling the API.

<Image alt="The dialog that pops up when the API consumer clicks Get Token." align="center" border={true} src="https://files.readme.io/915966b-get-token-password.png">
  The dialog that pops up when the API consumer clicks Get Token.
</Image>

> 📘 Client ID and Client Secret
>
> If your API consumers can receive access tokens without providing the Client ID and Client Secret as shown above, you have the option of using the **[Header](#add-header-authentication)** authentication set instead of OAuth2. The API provider can add an "authorization" header, and API consumers can add an access token directly when testing the API. This bypasses the Client ID and Client Secret workflow shown above.

## Add header authentication

Header authentication allows API providers to require API consumers to add one or more authorization related headers to API requests. Calls to the API must have valid values for these headers, otherwise the request should not succeed. The API provider is responsible for verifying these values and returning the proper response to the caller.

To enable header authorization for your API:

1. Navigate to **Studio (My APIs)**.
2. In the sidebar, click the **Hub Listing** tab for your API.
3. Click the **Gateway** tab.
4. For **Access Control > Authorization**, select **Header**.
5. Enter a **Name** for the header. The API consumer will need to add a header with this name and a valid value for the call to succeed.
6. Optionally enter a **Description**. This is shown as a label under the **Header Parameters** section when testing an API endpoint (see second screenshot below).
7. If desired, repeat this process to add more headers.
8. Click **Save**.

<Image alt="Configuring Header auth for an API." align="center" border={true} src="https://files.readme.io/47d3a10-hub-listing-header-auth.png">
  Configuring Header auth for an API.
</Image>

When an API consumer uses the API, they will have to provide header(s) with valid name-value pairs, as specified by the API provider. When testing an endpoint, under **Header Parameters**, the developer will see one or more **AUTHHEADER** headers that they need to specify values for. In the example below, the header parameter is named **HeaderAuth**.

<Image alt="The API consumer's view of Header authentication." align="center" border={true} src="https://files.readme.io/7ca5e3d-HeaderAuthConsumer.png">
  The API consumer's view of Header authentication.
</Image>

## Add query parameter authentication

Query authentication allows API providers to require API consumers to add one or more query string parameters to API requests. Calls to the API must have valid values for these query string parameters, otherwise the request should not succeed. The API provider is responsible for verifying these values and returning the proper response to the caller.

To enable query authentication for your API:

1. Navigate to **Studio (My APIs)**.
2. In the sidebar, click the **Hub Listing** tab for your API.
3. Click the **Gateway** tab.
4. For **Access Control > Authorization**, select **Query**.
5. Enter a **Name** for the query string parameter. The API consumer will need to add a query string parameter with this name and a valid value for the call to succeed.
6. Optionally enter a **Description**. This is shown as a label under the **Required Parameters** section when testing an API endpoint (see the second screenshot below).
7. If desired, repeat this process to add more query string parameters.
8. Click **Save**.

<Image alt="Configuring Query authorization for an API." align="center" border={true} src="https://files.readme.io/93d5672-hub-listing-query-parameter.png">
  Configuring Query authorization for an API.
</Image>

When an API consumer uses the API, they will have to provide query string parameter(s) with valid name-value pairs, as specified by the API provider. When testing an endpoint, under **Required Parameters**, the developer will see one or more parameters that they need to specify values for. In the example below, the query string parameter is named **myQueryParameter**.

<Image alt="The API consumer view of Query Parameter authentication." align="center" border={true} src="https://files.readme.io/1749ea5-QueryParameterConsumer.png">
  The API consumer view of Query Parameter authentication.
</Image>

## Add basic authentication

This option adds [basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) to API calls. The user ID and password are base64 encoded and passed in a request header as **Authorization: Basic`<base64>`** . When this RapidAPI Key Authentication Set option is selected, the API consumer must include this request header (in addition to the RapidAPI Authentication  headers described above, unless your API is not using the RapidAPI Proxy) in all calls to the API.

To enable basic authentication for your API:

1. Navigate to **Studio (My APIs)**.
2. In the sidebar, click the **Hub Listing** tab for your API.
3. Click the **Gateway** tab.
4. For **Access Control > Authorization**, select **Basic**.
5. Optionally enter a **Description**. This is shown as a label under the **Authorization** section when testing an API endpoint (see the second screenshot below).
6. Click **Save**.

<Image alt="Configuring Basic auth for an API." align="center" border={true} src="https://files.readme.io/746254b-hub-listing-basic-auth.png">
  Configuring Basic auth for an API.
</Image>

When an API consumer uses the API, they will also have to provide basic authentication credentials to successfully call the API. When testing an endpoint, the developer sees a **Header Parameter** named Authorization BASIC. Clicking the **Authenticate** button opens an **Authorization** dialog, where the API consumer enters a username and password. RapidAPI will convert that information to base64 when the call is made.

<Image title="Authenticate.png" alt={874} align="center" border={true} src="https://files.readme.io/a035a8e-Authenticate.png">
  An API consumer testing an API with Basic auth.
</Image>

<Image title="BasicAuth.png" alt={2456} align="center" border={true} src="https://files.readme.io/7f51ff1-BasicAuth.png">
  The popup that result from clicking Authenticate.
</Image>

## Add bearer authentication

This option adds bearer authentication to API calls. When this RapidAPI Key Authentication Set option is selected, the API consumer must include this request header (in addition to the RapidAPI Authentication  headers described above, unless your API is not using the RapidAPI Proxy) in all calls to the API.

To enable bearer authentication for your API:

1. Navigate to **Studio (My APIs)**.
2. In the sidebar, click the **Hub Listing** tab for your API.
3. Click the **Gateway** tab.
4. For **Access Control > Authorization**, select **Bearer**.
5. Optionally enter a **Description**. This is shown as a label under the **Authorization** section when testing an API endpoint (see the second screenshot below).
6. Click **Save**.

<Image alt="Configuring Basic auth for an API." align="center" border={true} src="https://files.readme.io/edb03b4-hub-listing-bearer-auth.png">
  Configuring Basic auth for an API.
</Image>

When an API consumer uses the API, they will also have to provide a valid Authorization value to successfully call the API. When testing an endpoint, the developer sees a **Header Parameter** named Authorization BEARER.

<Image alt="An API consumer testing an API with Bearer auth." align="center" border={true} src="https://files.readme.io/b7b7837-api-listing-bearer-auth.png">
  An API consumer testing an API with Bearer auth.
</Image>