Defining an HTTP bearer security scheme

An HTTP bearer security scheme is used to generate access tokens that are exchanged between the server and the client when calling the API operations.

About this task

For information on the use of bearer tokens with OpenAPI 3 APIs, see Bearer Authentication in the OpenAPI 3 specification.

If an HTTP bearer token is found in the request, its value is stored within the context as api->security->bearer_token. If an external URL validation is invoked, any response with a status code of 200 is stored within the context as api->security->bearer_validation_response.

  • This task relates to configuring an OpenAPI 3.0 API definition. For details on how to configure an OpenAPI 2.0 API definition, see Editing an OpenAPI 2.0 API definition.
  • OpenAPI 3.0 APIs are supported only with the DataPower® API Gateway, not with the DataPower Gateway (v5 compatible).
  • For details of current OpenAPI 3.0 support limitations, see OpenAPI 3.0 support in IBM® API Connect.

You can complete this task either by using the API Designer UI application, or by using the browser based API Manager UI.

At any time, you can switch directly to the underlying OpenAPI YAML source that corresponds to the design form in the user interface by clicking the Source icon OpenAPI Source icon. To return to the design form, click the Form icon Form icon.


  1. Open the required API for editing, as described in Editing an OpenAPI 3.0 API definition.
  2. Expand Components > Security Schemes.
  3. Click Add.
  4. In the Add Object dialog box, provide the following information:
    • Security Scheme Name (Key) - Provide a descriptive name for the new scheme.
    • Security Scheme Type - Select http.
    • Scheme - Select Bearer.
    • Bearer Format - Select JWT.
    • Validation Method - Select a method. If you select external-url, provide the following additional information:
      • Validation Endpoint - Provide the URL of the server used for validation. To ensure a secure connect, the URL should use the https protocol.
      • TLS Profile name - If the validation endpoint uses the https protocol, select the name of the TLS client profile to use for a secure connection.
    • Description - Provide a description of the JWT scheme.
  5. Click Create to create the new scheme.
  6. Click Save in the page header.