Configuring Implemented Security Schemes

RESTful APIs dealing with sensitive data need protection against unwanted access, and threats and attacks from external entities. To ensure endpoints handling private information¹ only reply to verified clients with authorized access, authentication and authorization mechanisms are implemented.

Most APIs implement standard protocols for authentication and authorization. In the Docs to OpenAPI plugin, we define protocols used through the Security tab.

Security Scheme Fields

Fields with an asterisk (*) are required

In order to add a property to the schema, required fields must be provided.

Name	Description
Security Id*	Identifier for the security scheme.
Type*	The type of security protocol implemented; choices are: API Key, HTTP, OAuth 2, and OpenID Connect.
Description	A short description of the security scheme.
Operations	A dropdown wherein you can select or deselect operations to indicate the use of this security scheme.

Security Types

API Key

This is for APIs that support authentication using API keys, or cookies. Selecting this option displays the following additional fields:

Fields with an asterisk (*) are required

In order to add a property to the schema, required fields must be provided.

Name	Description	Example
Name*	The API key's name in the request.	Api-Key
In*	Which part of the request contains the API key to be sent.	Header

HTTP

Select HTTP for APIs that support HTTP-based authentication schemes. Selecting this option displays the following additional fields:

Fields with an asterisk (*) are required

In order to add a property to the schema, required fields must be provided.

Name	Description	Example
Scheme	The HTTP authentication scheme to be used.	Basic, Bearer, or Digest
Bearer Format	Specifies the format for the bearer token, used mainly for documentation purposes.	JWT

OAuth 2

Add this scheme if your API supports authorization via OAuth 2. Selecting this option displays the following additional fields:

Name	Description	Example
OAuth Flow*	The OAuth Flow describes how a user or client requests an access token from the authorization server. There are four types of flows provided by OAuth 2: (1) implicit, for single-page apps; (2) password (resource owner password credentials grant), for clients trusted with user credentials; (3) clientCredentials, for resource owners; and (4) authCode, for web app clients executing on the server.
Auth Url	The flow's authorization URL; can be relative to the API's server URL(s).	https://forumock.io/oauth/authorize
Token Url	The flow's token URL; can be relative to the API's server URL(s).
Refresh Url	Where access tokens are obtained; can be relative to the API's server URL(s).
Enabled	Check to enable OAuth flow.
Scopes	Available scopes which are used to limit access granted to an access token.

Scopes have the following fields:

Name	Description	Example
Name	The name of the scope.	write:accounts
Description	Description of the scope.	Ability to manage user accounts

OpenID Connect

Choose OpenID Connect for authentication via OpenID Connect Discovery. Selecting this option displays the following additional fields:

Name	Description	Example
Description	Description for this type of authentication.
OpenID Connect Url	The connection URL.

Adding a New Security Scheme

You can add a new security scheme by following these steps:

1. Click the green, '+'-labeled button at the top left corner of the Security tab.
2. Enter an ID for your scheme in the Security Id field.
3. Select the type of security scheme you want.
4. Fill out the remaining fields based on the selected type.
5. (Optional) Provide a brief description for your scheme and select the operations that will use it.
6. Click the floppy disk icon to save.

Select applicable security schemes in the Operations tab

Aside from the Security tab, you can also assign security schemes for operations in the Operations tab.

---

1. Such as bank accounts, medical records, and social security numbers. ↩