Configuring API Authorization (legacy)

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.

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 (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.

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, 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
• Header
• Query
• Basic
• Bearer

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 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 this link 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.

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.

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 to enable API consumers to obtain tokens without needing to know the Client ID or Client Secret.

📘

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 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 this link 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 this page.
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.

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.

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 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.

📘

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 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 this link 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.

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.

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.

📘

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 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.

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.

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.

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.

Add basic authentication

This option adds basic authentication to API calls. The user ID and password are base64 encoded and passed in a request header as Authorization: Basic . 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.

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.

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.

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.