Skip to content

Security Tab - Spec Editor

The Security tab lets you create, view and edit the security schemes for the spec selected from the List of Specifications on the Specs page.

All security schemes used by the API must be defined in the global components/securitySchemes section in the OpenAPI spec. This section contains a list of named security schemes, where each scheme can be of type:

http – for Basic, Bearer and other HTTP authentications schemes apiKey – for API keys and cookie authentication oauth2 – for OAuth 2 openIdConnect – for OpenID Connect Discovery

Security Schemes Screen

The screen shows the tabs for the available 5 types of security schemes:

  1. BasicAuth
  2. BearerAuth
  3. APIKeyAuth
  4. OpenID
  5. OAuth2

BasicAuth

Create a BasicAuth Scheme

When no schemes are created yet, the screen looks like:

Select the tab BasicAuth on the screen and click the button.

Enter the security scheme name which is an arbitrary name that will be used to refer to this definition from other places in the spec, and the description. Click the button.

The basic security scheme gets created and the Security screen is updated.

The tab now shows the number of Basic auth schemes created.

Also a dropdown list of the security schemes created appear now to which the newly created Security Scheme is added.

Use the button to delete the selected scheme.

The created Security Scheme gets added to global components/securitySchemes section of the underlying OAPI/SWAGGER:

  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1
After you have defined the security schemes in the securitySchemes section, you can apply them to the whole API or individual operations by adding the security section on the root level or operation level, respectively. When used on the root level, security applies the specified security schemes globally to all API operations, unless overridden on the operation level.

The button lets you add the security scheme to the root or the global level.

When the button is clicked, the underlying OAPI/SWAGGER gets updated. The selected security scheme is added to the global "security" array:

security:
  - BasicAuth1: []
components:
  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1

BearerAuth

Create a BearerAuth Scheme

Select the tab BearerAuth on the screen and click the button.

Enter the security scheme name which is an arbitrary name that will be used to refer to this definition from other places in the spec, and the description. Click the button.

The bearer security scheme gets created and the Security screen is updated.

The tab now shows the number of Bearer auth schemes created.

Also a dropdown list of the security schemes created appear now to which the newly created Security Scheme is added.

Use the button to delete the selected scheme.

The created Security Scheme gets added to global components/securitySchemes section of the underlying OAPI/SWAGGER:

 components:
  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1
    BearerAuth1:
      type: http
      scheme: bearer
      description: Bearer Auth 1
After you have defined the security schemes in the securitySchemes section, you can apply them to the whole API or individual operations by adding the security section on the root level or operation level, respectively. When used on the root level, security applies the specified security schemes globally to all API operations, unless overridden on the operation level.

The button lets you add the security scheme to the root or the global level.

When the button is clicked, the underlying OAPI/SWAGGER gets updated. The selected security scheme is added to the global "security" array:

security:
  - BasicAuth1: []
  - BearerAuth1: []
components:
  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1
    BearerAuth1:
      type: http
      scheme: bearer
      description: Bearer Auth 1

APIKeyAuth

Create an ApiKeyAuth scheme

Select the tab ApiKeyAuth on the screen and click the button.

Fill the form. Enter the security scheme name which is an arbitrary name that will be used to refer to this definition from other places in the spec, and the description. Select the parameter type and the actual parameter or cookie to be used from the dropdown. Click the button.

The APIKeyAuth security scheme gets created and the Security screen is updated.

The tab now shows the number of ApiKeyAuth schemes created.

Also a dropdown list of the security schemes created appear now to which the newly created Security Scheme is added.

Use the button to delete the selected scheme.

The created Security Scheme gets added to global components/securitySchemes section of the underlying OAPI/SWAGGER:

 components:
  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1
    BearerAuth1:
      type: http
      scheme: bearer
      description: Bearer Auth 1
    ApiKeyAuth1:
      type: apiKey
      in: query
      name: q1
      description: ApiKeyAuth 1
After you have defined the security schemes in the securitySchemes section, you can apply them to the whole API or individual operations by adding the security section on the root level or operation level, respectively. When used on the root level, security applies the specified security schemes globally to all API operations, unless overridden on the operation level.

The button lets you add the security scheme to the root or the global level.

When the button is clicked, the underlying OAPI/SWAGGER gets updated. The selected security scheme is added to the global "security" array:

security:
  - BasicAuth1: []
  - BearerAuth1: []
  - ApiKeyAuth1: []
components:
  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1
    BearerAuth1:
      type: http
      scheme: bearer
      description: Bearer Auth 1
    ApiKeyAuth1:
      type: apiKey
      in: query
      name: q1
      description: ApiKeyAuth 1

OpenID

Create an OpenID scheme

Select the tab OpenID on the screen and click the button.

Fill the form. Enter the security scheme name which is an arbitrary name that will be used to refer to this definition from other places in the spec, and the description.

The default value of the openID connect/server URL is provided in the form as https://server.com/.well-known/openid-configuration.

Click the button.

The OpenID security scheme gets created and the Security screen is updated.

The tab now shows the number of OpenID schemes created.

Also a dropdown list of the security schemes created appear now to which the newly created Security Scheme is added.

Use the button to delete the selected scheme.

The created Security Scheme gets added to global components/securitySchemes section of the underlying OAPI/SWAGGER:

 components:
  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1
    BearerAuth1:
      type: http
      scheme: bearer
      description: Bearer Auth 1
    ApiKeyAuth1:
      type: apiKey
      in: query
      name: q1
      description: ApiKeyAuth 1
    openID1:
      type: openIdConnect
      openIdConnectUrl: 'https://example.com/.well-known/openid-configuration'
      description: Test OpenID
After you have defined the security schemes in the securitySchemes section, you can apply them to the whole API or individual operations by adding the security section on the root level or operation level, respectively. When used on the root level, security applies the specified security schemes globally to all API operations, unless overridden on the operation level.

The button lets you add the security scheme to the root or the global level. When the button is clicked, a popup appears where you are required to enter the scopes (the comma separated values).

Click the button. The button now changes to:

the underlying OAPI/SWAGGER gets updated. The selected security scheme is added to the global "security" array:

security:
  - BasicAuth1: []
  - BearerAuth1: []
  - ApiKeyAuth1: []
  - openID1:
      - read
      - write
components:
  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1
    BearerAuth1:
      type: http
      scheme: bearer
      description: Bearer Auth 1
    ApiKeyAuth1:
      type: apiKey
      in: query
      name: q1
      description: ApiKeyAuth 1
    openID1:
      type: openIdConnect
      openIdConnectUrl: 'https://example.com/.well-known/openid-configuration'
      description: Test OpenID

OAuth2

Create an OAuth2 scheme

Select the tab OAuth2 on the screen and click the button.

Fill the form. Enter the security scheme name which is an arbitrary name that will be used to refer to this definition from other places in the spec, and the description.

You need to select the Flow or the grant type. Read about the Oauth2 and flows here

Following types of flows can be used.

  1. Authorization code
  2. Implicit
  3. Client Credentials
  4. Resource owner password credentials (or just password)
Authorization code type input form

Click the button.

The OAuth2 security scheme gets created and the Security screen is updated which can be edited to add more flows and scopes within the selected flow type.

The tab now shows the number of OAuth2 schemes created.

Also a dropdown list of the security schemes created appear now to which the newly created Security Scheme is added.

Use the button to delete the selected scheme.

The created Security Scheme gets added to global components/securitySchemes section of the underlying OAPI/SWAGGER:

 components:
  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1
    BearerAuth1:
      type: http
      scheme: bearer
      description: Bearer Auth 1
    ApiKeyAuth1:
      type: apiKey
      in: query
      name: q1
      description: ApiKeyAuth 1
    openID1:
      type: openIdConnect
      openIdConnectUrl: 'https://example.com/.well-known/openid-configuration'
      description: Test OpenID
    testOAuth2:
      type: oauth2
      description: 'Testing OAuth2 '
      flows:
        authorizationCode:
          authorizationUrl: 'https://example.com/oauth/authorize'
          tokenUrl: 'https://example.com/oauth/token'
          scopes:
            read: Read the clients
            write: modify clients information in your account
After you have defined the security schemes in the securitySchemes section, you can apply them to the whole API or individual operations by adding the security section on the root level or operation level, respectively. When used on the root level, security applies the specified security schemes globally to all API operations, unless overridden on the operation level.

The button lets you add the security scheme to the root or the global level. When the button is clicked, a popup appears where you are required to enter the scopes (the comma separated values).

Click the button. The button now changes to:

the underlying OAPI/SWAGGER gets updated. The selected security scheme is added to the global "security" array:

security:
  - BasicAuth1: []
  - BearerAuth1: []
  - ApiKeyAuth1: []
  - openID1:
      - read
      - write
  - testOAuth2:
      - read
components:
  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1
    BearerAuth1:
      type: http
      scheme: bearer
      description: Bearer Auth 1
    ApiKeyAuth1:
      type: apiKey
      in: query
      name: q1
      description: ApiKeyAuth 1
    openID1:
      type: openIdConnect
      openIdConnectUrl: 'https://example.com/.well-known/openid-configuration'
      description: Test OpenID
    testOAuth2:
      type: oauth2
      description: 'Testing OAuth2 '
      flows:
        authorizationCode:
          authorizationUrl: 'https://example.com/oauth/authorize'
          tokenUrl: 'https://example.com/oauth/token'
          scopes:
            read: Read the clients
            write: modify clients information in your account
Implicit type input form

To add an implicit type flow in the existing scheme created above (testOAuth2), use the form:

To create a new OAuth2 scheme with implicit type flow, click the button.

and click the button.

The OAuth2 security scheme gets created and the Security screen is updated which can be edited to add more flows and scopes within the selected flow type.

The tab now shows the number of OAuth2 schemes created.

Also a dropdown list of the security schemes created appear now to which the newly created Security Scheme is added.

Use the button to delete the selected scheme.

The created Security Scheme gets added to global components/securitySchemes section of the underlying OAPI/SWAGGER:

 components:
  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1
    BearerAuth1:
      type: http
      scheme: bearer
      description: Bearer Auth 1
    ApiKeyAuth1:
      type: apiKey
      in: query
      name: q1
      description: ApiKeyAuth 1
    openID1:
      type: openIdConnect
      openIdConnectUrl: 'https://example.com/.well-known/openid-configuration'
      description: Test OpenID
    testOAuth2:
      type: oauth2
      description: 'Testing OAuth2 '
      flows:
        authorizationCode:
          authorizationUrl: 'https://example.com/oauth/authorize'
          tokenUrl: 'https://example.com/oauth/token'
          scopes:
            read: Read the clients
            write: modify clients information in your account
        implicit:
          authorizationUrl: 'https://example.com/oauth/authorize'
          scopes:
            read_clients: Read the clients
            edit_client: Edit a particular client
    testOAuth2-1:
      type: oauth2
      description: Testing OAuth2 with Implicit flow
      flows:
        implicit:
          authorizationUrl: 'https://example.com/oauth/authorize'
          scopes:
            read_clients: Read the clients
            edit_client: Edit a particular client
After you have defined the security schemes in the securitySchemes section, you can apply them to the whole API or individual operations by adding the security section on the root level or operation level, respectively. When used on the root level, security applies the specified security schemes globally to all API operations, unless overridden on the operation level.

The button lets you add the security scheme to the root or the global level. When the button is clicked, a popup appears where you are required to enter the scopes (the comma separated values).

Click the button. The button now changes to:

the underlying OAPI/SWAGGER gets updated. The selected security scheme is added to the global "security" array:

security:
  - BasicAuth1: []
  - BearerAuth1: []
  - ApiKeyAuth1: []
  - openID1:
      - read
      - write
  - testOAuth2:
      - read
components:
  securitySchemes:
    BasicAuth1:
      type: http
      scheme: basic
      description: Basic Auth Scheme 1
    BearerAuth1:
      type: http
      scheme: bearer
      description: Bearer Auth 1
    ApiKeyAuth1:
      type: apiKey
      in: query
      name: q1
      description: ApiKeyAuth 1
    openID1:
      type: openIdConnect
      openIdConnectUrl: 'https://example.com/.well-known/openid-configuration'
      description: Test OpenID
    testOAuth2:
      type: oauth2
      description: 'Testing OAuth2 '
      flows:
        authorizationCode:
          authorizationUrl: 'https://example.com/oauth/authorize'
          tokenUrl: 'https://example.com/oauth/token'
          scopes:
            read: Read the clients
            write: modify clients information in your account
Client Credentials type input form

Similar to Implicit Type.

Password type input form

Similar to Implicit Type.