Build a new connector with Postman

3. Authentication with OAuth 2.0

OAuth 2.0 is a protocol that lets Digital Assistant request authorization to access private details in external applications without needing a user's password. Postman connectors that make requests to services which require authentication must first authorize with the application via OAuth 2.0 to generate a token. This token is then is sent alongside future requests to return relevant data to a logged in user.

In this example, we will authenticate with Gitlab via OAuth 2.0's Web application flow, enabling us to create API requests to Gitlab as a logged-in user. To do so, we must provide Postman with details for Digital Assistant, as well as authentication details from service we're connecting to.

Configuring scopes

Scopes are a mechanism in OAuth 2.0 which can limit an application's access to a user's account. Digital Assistant will only ever request access to the scopes you define in your connector.

You must ensure that the scopes required to access the endpoints you wish to use in your connector are defined. Scopes are defined in both Postman collections (connectors) and Postman requests (Cards).

  • At the collection level, required scopes are scopes that are needed for the connector to authenticate with the API, or scopes that are always needed by the API. Scopes should include scopes that may be needed by requests, and optionally can include commonly used scopes that might be required in the future.
  • At the request level, required scopes are scopes that the request needs to access relevant API endpoints.

These scopes are defined in the collection and request metadata. You can access this by hovering on the collection and clicking the three dots to open the More actions menu, then selecting Edit.

The collection editor modal will open, with the description tab selected.

The expected format for scopes can be found in Create a new collection. Scopes should be entered as a bullet-point list in Markdown, and can optionally have descriptions.

Incorrectly defined or missing scopes may lead to requests failing. Ensure you have reviewed the level of access needed by requests you create, as well as generic scopes needed to access the API, prior to publishing your connector.

Configuring the authorization

In Postman connectors, OAuth 2.0 authorization is managed at a Collection level. The Digital Assistant OAuth2 token manager uses Postman variables to access these details.

To begin, hover on the collection and click the three dots to open the More actions menu, then select Edit. This will open the collection editor modal.

To create the required variables, navigate to the Variables tab.

The details shown are required for all Authorization Code grant type OAuth tokens, but their values will differ between external applications. Ensure you consult the API documentation of the service you're connecting to.

The following details are required to generate an OAuth token. Some values have been provided for authentication with Github's service.

External application URL where the user can authenticate
Value for Gitlab:
External application URL which generates access tokens
Value for Gitlab:
Digital Assistant's unique identifier to the external application
Digital Assistant's unique identifier to the external application
_Scopes (optional)
Defines the level of access Digital Assistant needs to the external application. This field is required only for testing requests in Postman locally, and can be equal to a collection's required scopes and scopes.
Value for Gitlab: api

To generate _ClientId and _ClientSecret values for Gitlab, register a new application for Digital Assistant in Gitlab OAuth Applications with the Redirect URI Digital Assistant requires access to the api scope.

When complete, your Variables tab should look as below.

Generating a token

In order to generate the OAuth token from the details entered, navigate to the Authorization tab and select OAuth 2.0 as the Type. In the panel on the right, click Get New Access Token.

In the modal that opens, complete the form using the variables we defined previously. Set the Callback URL to and the State to dev.

OAuth specification advises sending a static State parameter with each request to an OAuth authorization service. For development purposes, a static value is acceptable. In a production environment, Digital Assistant sends a unique value with each request and validates it against the one in the redirect request for enhanced security.

To request the token, click Request Token. A window will open, prompting you to log in to the GitLab account you want to use with Digital Assistant. Enter your GitLab credentials and click Sign in to continue.

You will then be prompted to authorize Digital Assistant to use your account. The scope of access will be confirmed in this prompt. Select Authorize to continue.

Once Gitlab has issued your OAuth token, the details of the token will be displayed. Select Use Token to use this OAuth token with your Postman collection.

Finally, select Update to save your changes.

Configuring the request

To test our OAuth connection to Gitlab, we will create a request to the Gitlab API to get information from the version endpoint.

To do so, create a new request in the working Collection and set the request URL to Leave the request type as GET.

To make the request, click Send. If a user has successfully authenticated, a 200 OK response will be received with some JSON in the response body.