Configuring API Security

📘

Moved to the Definitions tab

This functionality has (or soon will be) moved to the Definitions tab. For the legacy Hub Listing > Gateway tab documentation, see Configuring API Authorization (legacy).

Authorization overview

By default, when you add an API to the Hub and use the Rapid 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 security schemes, as described below.

RapidAPI Auth

The default RapidAPI Auth is used for any API that is configured to use the Rapid proxy. All APIs on rapidapi.com use the Rapid proxy. For Enterprise Hubs, APIs can be configured to not use the Rapid proxy.

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 Rapid 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 Rapid proxy, you must pass valid RapidAPI Auth headers, even if you choose additional forms of authorization, as described below.

📘

Not using the Rapid proxy

If your API does not use the Rapid proxy, the Rapid 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 Rapid proxy understands their meaning.

The other types of authorization (security schemes) 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.

Additional types of authorization

The additional types 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 the default RapidAPI Auth, you can require these other forms of authorization for your API:

• OAuth2
• API Key
• HTTP

These are set using the Hub Listing > Definitions > Security tab, 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 authorization 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.

Security schemes

Additional forms of authorization are added using security schemes. To add a scheme, click New Scheme (see the top screenshot above) and the following will be displayed:

You then specify a name and description for your security scheme. You then select one of these values for the Authorization set dropdown (details on each of these choices are provided below):

• OAuth 2.0
• API Key
• HTTP

Specifying the security scheme endpoints

Each security scheme can apply to a single endpoint, multiple endpoints, or all of the API's endpoints. In the Endpoints dropdown, select All Endpoints if the security scheme should be applied to all of the API's endpoints. Otherwise, select one or more endpoints for which the security scheme applies. You then remove the All Endpoints entry so that the security scheme only applies to the selected endpoints.

OAuth 2.0 authorization

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 Definitions tab.
4. Click the Security tab.
5. Click New Scheme.
6. Enter a name for the scheme.
7. To the right, select the endpoints that this security scheme applies to (or select All Endpoints).
8. Add an optional Description for the scheme. In the API listing, this text will be shown to API consumers with the Authorization header (see the API consumer dialog below).
9. For Authorization set, select OAuth 2.0.
10. For Token Header Prefix, enter any prefix that is added to the Authorization header before the token. Some API gateways might require this value.
11. For Grant Type, select Client Credentials.
12. For Token URL, enter the URL where calls are made to obtain a token for the API.
13. 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.
14. 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.
15. If your authorization server expects client credentials to be sent as a JWT token, check the JWT format checkbox. In the API listing, API consumers will then need to add the Client ID, Client Secret, Private Key (by uploading a local file), JWT Algorithm, and optionally any Headers sent to the authorization server. See the fourth screenshot below to see the the API consumer experience if JWT format is checked.
16. For Separator, select either Space or Comma. This separator setting is used if you specify more than one OAuth scope.
17. 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.
18. 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 Authorization dialog (below), where the API consumer enters the Client ID and Client Secret needed to obtain a token. (If the API uses JWT, the consumer also must also provide the private key and specify the JWT algorithm, as shown in the second screenshot below.) 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. For JWT, the private key and JWT algorithms are also automatically provided.

📘

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 API Key authorization 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 Definitions tab.
4. Click the Security tab.
5. Click New Scheme.
6. Enter a name for the scheme.
7. To the right, select the endpoints that this security scheme applies to (or select All Endpoints).
8. Add an optional Description for the scheme. In the API listing, this text will be shown to API consumers with the Authorization header (see the API consumer dialog below).
9. For Authorization set, select OAuth 2.0.
10. For Token Header Prefix, enter any prefix that is added to the Authorization header before the token. Some API gateways might require this value.
11. For Grant Type, select Authorization Code.
12. 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.
13. For Token URL, enter the URL (often ending in /oauth2/token) where calls are made to obtain a token for the API.
14. Callback URL is populated by Rapid. This is the Rapid URL that will be called when your application is authorized.
15. 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.
16. Check the Require Client Secret checkbox if your API consumers should be prompted for the client secret. Some APIs may not require client secrets.
17. For With 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.
18. 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.
19. For Separator, select either Space or Comma. This separator setting is used if you specify more than one scope.
20. 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.
21. 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 Authorization 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 API Key authorization 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 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 Definitions tab.
4. Click the Security tab.
5. Click New Scheme.
6. Enter a name for the scheme.
7. To the right, select the endpoints that this security scheme applies to (or select All Endpoints).
8. Add an optional Description for the scheme. In the API listing, this text will be shown to API consumers with the Authorization header (see the API consumer dialog below).
9. For Authorization set, select OAuth 2.0.
10. For Token Header Prefix, enter any prefix that is added to the Authorization header before the token. Some API gateways might require this value.
11. For Grant Type, select Password.
12. For Token URL, enter the URL where calls are made to obtain a token for the API.
13. 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.
14. 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.
15. For Separator, select either Space or Comma. This separator setting is used if you specify more than one OAuth scope.
16. 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.
17. 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 Authorization dialog (below), where the API consumer enters the Client ID, Client Secret, Username, and Password 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 API Key authorization 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.

API Key authorization

API Key authorization includes two types: Header and Query string parameter. Each is described separately below.

Header authorization

Header authorization allows API providers to require API consumers to add one or more authorization related headers (using multiple security schemes) 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 Definitions tab.
4. Click the Security tab.
5. Click New Scheme.
6. Enter a name for the scheme.
7. To the right, select the endpoints that this security scheme applies to (or select All Endpoints).
8. Add an optional Description for the scheme.
9. For Authorization set, select API Key.
10. Enter a Key for the header. This is the name of the header. The API consumer will need to add a header with this name and a valid value for the call to succeed.
11. Optionally enter a Description for the header. This is shown as a label under the Header Parameters section when testing an API endpoint (see second screenshot below).
12. For Add to, select Header.
13. Click Save.

If you want to set up more headers, repeat the process above (creating a new security scheme).

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.

Query string parameter authorization

Query authorization allows API providers to require API consumers to add one or more (using multiple security schemes) 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 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 Definitions tab.
4. Click the Security tab.
5. Click New Scheme.
6. Enter a name for the scheme.
7. To the right, select the endpoints that this security scheme applies to (or select All Endpoints).
8. Add an optional Description for the scheme.
9. For Authentication set, select API Key.
10. Enter a Key for the query string parameter. This is the name of the parameter. The API consumer will need to add a query string parameter with this name and a valid value for the call to succeed.
11. Optionally enter a Description for the parameter. This is shown as a label under the Required Parameters section when testing an API endpoint (see the second screenshot below).
12. For Add to, select Query.
13. Click Save.

If you want to set up more parameters, repeat the process above (creating a new security scheme).

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.

HTTP authorization

HTTP authorization includes two types: Basic and Bearer. Each is described separately below.

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 Definitions tab.
4. Click the Security tab.
5. Click New Scheme.
6. Enter a name for the scheme.
7. To the right, select the endpoints that this security scheme applies to (or select API level).
8. Optionally enter a Description for the header. This is shown as a label under the Header Parameters section when testing an API endpoint (see second screenshot below).
9. For Authorization set, select HTTP.
10. For Scheme, select Basic.

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. Rapid will convert that information to base64 when the call is made.

Bearer authentication

This option adds bearer authentication to API calls. When this option is selected, the API consumer must add a value for the Authorization request header (in addition to the Rapid authorization headers described above, unless your API is not using the Rapid 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 Definitions tab.
4. Click the Security tab.
5. Click New Scheme.
6. Enter a name for the scheme.
7. To the right, select the endpoints that this security scheme applies to (or select All Endpoints).
8. Add an optional Description for the scheme. This is shown as a label under the Authorization section when testing an API endpoint (see the second screenshot below).
9. For Authorization set, select HTTP.
10. For Scheme, select Bearer.

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.