> For the complete documentation index, see [llms.txt](https://eazyapi-1.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eazyapi-1.gitbook.io/docs/open-api-guide/authentication/bearer-authentication.md).

# Bearer Authentication

**Bearer authentication** (also called **token authentication**) is an [HTTP authentication scheme](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) that involves security tokens called bearer tokens. The name “Bearer authentication” can be understood as “give access to the bearer of this token.” The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the `Authorization` header when making requests to protected resources:

{% code lineNumbers="true" %}

```yaml
Authorization: Bearer <token>
```

{% endcode %}

The Bearer authentication scheme was originally created as part of [OAuth 2.0](/docs/open-api-guide/authentication/oauth-2.0.md) in [RFC 6750](https://tools.ietf.org/html/rfc6750), but is sometimes also used on its own. Similarly to [Basic authentication](/docs/open-api-guide/authentication/basic-authentication.md), Bearer authentication should only be used over HTTPS (SSL).

### Describing Bearer Authentication <a href="#how" id="how"></a>

In OpenAPI 3.0, Bearer authentication is a security scheme with `type: http` and `scheme: bearer`. You first need to define the security scheme under `components/securitySchemes`, then use the `security` keyword to apply this scheme to the desired scope – global (as in the example below) or specific operations:

{% code lineNumbers="true" %}

```yaml
openapi: 3.0.0
...
# 1) Define the security scheme type (HTTP bearer)
components:
  securitySchemes:
    bearerAuth:            # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT    # optional, arbitrary value for documentation purposes
# 2) Apply the security globally to all operations
security:
  - bearerAuth: []         # use the same name as above
```

{% endcode %}

Optional `bearerFormat` is an arbitrary string that specifies how the bearer token is formatted. Since bearer tokens are usually generated by the server, `bearerFormat` is used mainly for documentation purposes, as a hint to the clients. In the example above, it is "JWT", meaning [JSON Web Token](https://jwt.io/). The square brackets `[]` in *bearerAuth: \[]* contain a list of security scopes required for API calls. The list is empty because scopes are only used with OAuth 2 and [OpenID Connect](/docs/open-api-guide/authentication/openid-connect-discovery.md). In the example above, Bearer authentication is applied globally to the whole API. If you need to apply it to just a few operations, add `security` on the operation level instead of doing this globally:

{% code lineNumbers="true" %}

```yaml
paths:
  /something:
    get:
      security:
        - bearerAuth: []
```

{% endcode %}

Bearer authentication can also be combined with other authentication methods as explained in [Using Multiple Authentication Types](/docs/open-api-guide/authentication.md#multiple).

### 401 Response <a href="#response" id="response"></a>

You can also define the 401 “Unauthorized” response returned for requests that do not contain a proper bearer token. Since the 401 response will be used by multiple operations, you can define it in the global `components/responses` section and reference elsewhere via `$ref`.

{% code lineNumbers="true" %}

```yaml
paths:
  /something:
    get:
      ...
      responses:
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        ...
    post:
      ...
      responses:
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        ...
components:
  responses:
    UnauthorizedError:
      description: Access token is missing or invalid
```

{% endcode %}

To learn more about describing responses, see [Describing Responses](/docs/open-api-guide/describing-responses.md).