REST APIs use authorization to ensure that a client has secure access only to the resources permitted by their roles. If you are building or integrating with a 3rd party API, you can choose between Basic Auth, Bearer Tokens, and OAuth2.0.

Auth details can be added to a header, body, or as parameters to a request. However, if you enter your auth details in the Authorization Tab, Hoppscotch will automatically modify the relevant parts of the request based on your chosen Auth type. Storing Auth Credentials or Bearer Tokens as environment variables, lets you re-use these more safely and efficiently.

​
Inherit

Inherit Authorization allows requests to automatically adopt the authorization settings defined at the parent collection or subfolder level. This means you only need to configure the authorization once, and all nested requests will inherit these settings, ensuring consistency and saving time during setup.

​
Basic Auth

Basic Authentication is one of the simplest methods to secure your API requests in Hoppscotch. It works by requiring a username and password to be sent along with each request. To get started, head to the Authorization tab and select Basic Auth as your authentication type. You’ll then input your verified username and password. When you send the request, Hoppscotch will automatically encode your credentials in the format:

Basic <Base64-encoded-credentials>
Basic Auth transmits your credentials in a way that can be easily decoded, so it’s best suited for secure channels like HTTPS to prevent exposure.

​
Bearer Tokens

Bearer Tokens are used to authenticate requests using an access token, which can be a simple string or a JWT (JSON Web Token). To set it up, choose Bearer from the Authorization tab and enter your access token. Hoppscotch will include the token in the request header as:

Bearer <your-access-token>
Be aware that if your token expires, you’ll need to refresh it manually and update it in Hoppscotch. For better security, consider storing your token as an environment variable so that you can easily reference it in your requests.

​
API Key

API Keys are unique identifiers that help authenticate your requests to an API. In Hoppscotch, you can set up API Key authentication by selecting it from the Authorization tab. Here, you’ll need to fill in two fields: the Key, which is the name the API expects (like api_key or Authorization), and the Value, which is your actual API Key. You can also choose whether to pass this API Key as a Header or as a Query Parameter.

When using API Keys, keep an eye on the rate limits set by the API provider to avoid any issues. For improved security practices, store your API Key as an environment variable to facilitate easy management across different environments.

​
OAuth 2.0

OAuth 2.0 provides a secure way to let third-party applications access your resources without needing to share your passwords. Instead of directly passing credentials, you authenticate through a trusted service, which then issues an access token. This token allows your app to make API requests on your behalf.

OAuth 2.0 workflows are not fully supported in the Hoppscotch Desktop application and are currently a work in progress. We’re actively working on it, and it will function as intended soon!

​
Steps for OAuth 2.0 Setup

  1. In the “Authorization Tab” for a request, select OAuth 2.0 from the Authorization Type drop-down.
  2. Select the Grant Type from Authorization Code (with or without PKCE), Client Credentials, Password Credentials, and Implicit.
  3. Fill out the fields in the section below and click on “Generate Token” to generate a new access token.
  4. You can save the token to be re-used later.

​
Grant types

When using OAuth 2.0 authorization with Hoppscotch, you can utilize the following grant types:

​
1. Authorization Code

The Authorization Code grant is used when your application needs to access a user’s account. The user logs in to the OAuth provider and gives permission, allowing your app to receive a special code. You then use this code to request an access token that lets you access the user’s data.

To use the Authorization Code grant type, ensure the Callback URL is correctly configured (either https://hoppscotch.io/oauth for Hoppscotch Cloud or <your-domain>/oauth for self-hosted editions). Next, provide the Authorization Endpoint and Access Token Endpoint from the API provider, along with the Client ID (and the Client Secret if you choose to use it). You can also specify the desired permissions in the Scope field and pass the token as a Header or as a Query Parameter. Once you’ve filled in these fields, click Generate Token to get your access token.

If your API provider supports token refreshing, you can use the “Refresh Token” button in Hoppscotch to obtain a new access token without requiring the user to log in again.

​
Using PKCE

Opting for OAuth 2.0 with PKCE (Proof Key for Code Exchange), you gain the option to enhance security. Upon selecting PKCE, you can choose between SHA-256 or Plain algorithms.

​
2. Client Credentials

The Client Credentials grant is suitable for server-to-server interactions, where your application needs to access its own resources rather than user-specific data. This method relies on your app’s credentials to obtain an access token directly.

To obtain a token using Client Credentials grant type, input the Authorization Endpoint from the API provider, and fill in your Client ID. Including a Client Secret is optional.

You can now choose how the client credentials (Client ID and Client Secret) are sent to the server. Hoppscotch supports both:

  • Sending them in the body of the request (default behavior).
  • Sending them via Basic Authentication headers.

Just select your preferred method in the Client Authentication field to suit your security requirements.

​
3. Password Credentials

The Password Credentials grant allows you to authenticate users by sending their username and password directly to the API. This method is less secure and is generally discouraged for third-party applications.

To implement the Password credentials grant type in Hoppscotch, provide your API provider’s Authorization Endpoint, along with the Username and Password. Occasionally, you may also be required to supply a Client ID and Secret.

​
4. Implicit

The Implicit grant is intended for client-side applications, where the access token is returned immediately without the need for an authorization code. While this method simplifies the process, it does come with security risks.

To configure the Implicit grant type in Hoppscotch, make sure the Callback URL is set as required (either https://hoppscotch.io/oauth or <your-domain>/oauth). You will need to further provide the Authorization Endpoint and Client ID to generate the token.

​
OAuth Callback URL Configuration

When using OAuth 2.0 with Hoppscotch Cloud, the callback URL is fixed to https://hoppscotch.io/oauth while for self-hosted editions of Hoppscotch, the callback URL should be set to <your-domain>/oauth . You must configure this URL as a valid redirect URI in your OAuth provider’s settings. This is important because Hoppscotch handles all OAuth requests on the client side. When your OAuth provider redirects you to this URL, we process the response to obtain the token or authorization code. Any mismatch between the registered callback URL and what Hoppscotch uses will result in errors like INVALID_REDIRECT_URI during the authorization process.

The Callback URL is required only for Authorization Code and Implicit grant types. Other grant types do not need this configuration.

​
Digest

Digest Auth is a way to verify your identity without transmitting plain text passwords. Instead of sending your credentials directly as plain-text, it uses a challenge-response system to keep your information safe. When you attempt to access a restricted resource, the server responds with a 401 Unauthorized status and a WWW-Authenticate header. This header contains essential information, including a unique challenge that you will use to generate a valid response.

To configure Digest Auth in Hoppscotch, start by entering your Username and Password. For added security, you can also provide optional parameters like Realm and Nonce from the WWW-Authenticate header. Choose the appropriate Algorithm for hashing and define the Quality of Protection (QoP) to further secure your requests. You can also specify parameters such as Nonce Count, Client Nonce, and Opaque to further bolster the authentication process.

Digest Auth is supported exclusively when using the Hoppscotch Agent interceptor.

​
AWS Signature

AWS Signature is a method used to authenticate API requests made to AWS services. When you send a request, this configuration ensures that your request is genuine and has not been tampered with. It does this by using a process called HMAC (Hash-based Message Authentication Code), which creates a unique signature based on your request details.

To set up AWS Signature in Hoppscotch, enter your AWS Access Key and Secret Key to sign your requests. For advanced configuration, you can also provide details like the AWS Region where your service is hosted (like us-east-1), the Service Name of the specific AWS service you’re accessing (such as s3 or dynamodb), and a Service Token if you’re using temporary security credentials.

​
JWT

JWT (JSON Web Token) is a compact and secure way to transmit information between parties as a JSON object. It is commonly used for authentication and information exchange in web applications. In Hoppscotch, you can easily configure JWT authentication by selecting JWT from the Authorization tab. You can then enter your JWT Token directly, or if you have a JWT secret, you can use it to generate the token. This token will be included in the request header as:

Authorization: Bearer <your_jwt_token>

​
Managing Authorization at the Collection Level

When managing multiple requests within a collection, setting identical authorization configurations for each request individually can be tedious. It is now possible to set authorization at the collection level, ensuring it applies to all the requests stored within that collection.

To set collection-level authorization:

  • Right-click on a collection or a subfolder within a collection to open its properties.
  • Specify the authorization that all nested requests or folders should adhere to.
  • If a subfolder should inherit the properties of a parent collection, specify the authorization as inherit.