# 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](https://eazyapi-1.gitbook.io/docs/open-api-guide/authentication/oauth-2.0) in [RFC 6750](https://tools.ietf.org/html/rfc6750), but is sometimes also used on its own. Similarly to [Basic authentication](https://eazyapi-1.gitbook.io/docs/open-api-guide/authentication/basic-authentication), 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](https://eazyapi-1.gitbook.io/docs/open-api-guide/authentication/openid-connect-discovery). 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](https://eazyapi-1.gitbook.io/docs/open-api-guide/authentication/..#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](https://eazyapi-1.gitbook.io/docs/open-api-guide/describing-responses).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://eazyapi-1.gitbook.io/docs/open-api-guide/authentication/bearer-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.