OpenAPI
Security
Security Schemes
Bearer Security

Bearer Security Scheme in OpenAPI

The Bearer security scheme allows passing a token (most commonly a JWT) in the Authorization header.

A Bearer security scheme is generally used for short-lived tokens granted to your API users through an additional login mechanism. Using a JWT allows for storing additional metadata within the token, which can be helpful for some use cases, such as storing scopes for permissions models.

The fields for a Bearer security scheme are as follows:

FieldTypeRequiredDescription
typeString✅http
descriptionStringHuman-readable information. This may contain CommonMark syntax (opens in a new tab) to provide a rich description.
schemeString✅bearer
bearerFormatStringA hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
x-*ExtensionsAny number of extension fields can be added to the security scheme object to be used by tooling and vendors.
components:

  securitySchemes:

    auth:

      type: http

      scheme: bearer

      bearerFormat: JWT

security:

  - auth: []