Configuring API Authentication

Add extra security to your API.

Authentication overview

By default, when you add an API to the Hub, authentication called RapidAPI Authentication is used. This is the simplest form of authentication for consumers of the API, and the other types of authentication described here can be "added on" to this default authentication.

With RapidAPI authentication, each RapidAPI application in the Provider Dashboard has a single key named X-RapidAPI-Key. This same key is used for any APIs added to the application and must be added as a Header Parameter in every API request, as shown below.

In addition to RapidAPI authentication, you can require other forms of authentication for your API:

These are set using the RapidAPI Key Authentication Set dropdown (as shown below).

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 X-RapidAPI-Key header) in all calls to the API.

To enable basic authentication for your API:

  1. Navigate to the Provider Dashboard (My APIs).
  2. In the sidebar, click the Definition tab for your API.
  3. Click the API Specs tab.
  4. Click the Settings tab.
  5. For Access Control > Authentication > RapidAPI Key Authentication Set, select Add Basic.
  6. Optionally enter a Description. This is shown as a label under the Authorization section when testing an API endpoint (see the second screenshot below).
  7. 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 header authentication

Header authentication allows API providers to require API consumers to add one or more authentication-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 authentication for your API:

  1. Navigate to the Provider Dashboard (My APIs).
  2. In the sidebar, click the Definition tab for your API.
  3. Click the API Specs tab.
  4. Click the Settings tab.
  5. For Access Control > Authentication > RapidAPI Key Authentication Set, select Add Header.
  6. 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.
  7. Optionally enter a Description. This is shown as a label under the Header Parameters section when testing an API endpoint (see the second screenshot below).
  8. If desired, repeat this process to add more headers.
  9. 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 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 the Provider Dashboard (My APIs).
  2. In the sidebar, click the Definition tab for your API.
  3. Click the API Specs tab.
  4. Click the Settings tab.
  5. For Access Control > Authentication > RapidAPI Key Authentication Set, select Add Query.
  6. 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.
  7. 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).
  8. If desired, repeat this process to add more query string parameters.
  9. 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 OAuth2 authentication

OAuth2 is a token-based authorization protocol. Using this authentication method in RapidAPI, 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 authentication methods, there are more options to configure here.

RapidAPI supports two OAuth Grant Types, Client Credentials and Authorization Code. These are the most likely Grant Types used with APIs. We will discuss these separately.

Client Credentials Grant Type

To enable client credentials OAuth2 authentication for your API:

  1. Navigate to the Provider Dashboard (My APIs).
  2. In the sidebar, click the Definition tab for your API.
  3. Click the API Specs tab.
  4. Click the Settings tab.
  5. For Access Control > Authentication > RapidAPI Key Authentication Set, select Add OAuth2.
  6. For Grant Type, select Client Credentials.
  7. For Token URL, enter the URL where calls are made to obtain a token for the API.
  8. 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.
  9. For Separator, select either Space or Comma. This separator setting is used if you specify more than one scope.
  10. 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.
  11. 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.

Authorization Code Grant Type

To enable Authorization Code OAuth2 authentication for your API:

  1. Navigate to the Provider Dashboard (My APIs).
  2. In the sidebar, click the Definition tab for your API.
  3. Click the API Specs tab.
  4. Click the Settings tab.
  5. For Access Control > Authentication > RapidAPI Key Authentication Set, select Add OAuth2.
  6. For Grant Type, select Authorization Code.
  7. For Authorization URL, enter the URL where calls are made to obtain an authorization code for the API. This code in needed before tokens can be obtained.
  8. For Token URL, enter the URL where calls are made to obtain a token for the API.
  9. 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.
  10. For Separator, select either Space or Comma. This separator setting is used if you specify more than one scope.
  11. 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.
  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.