### Install @elysia/bearer with bun add

Source: https://github.com/elysiajs/elysia-bearer/blob/main/README.md

Install the @elysia/bearer plugin using the Bun package manager.

```bash
bun add @elysia/bearer
```

--------------------------------

### Usage: Install bearer plugin with .use()

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/api-reference/index.md

Shows the typical usage of the plugin: import `bearer` from `@elysia/bearer`, install it with `.use(bearer())`, and access the extracted token via the `bearer` context property in a route handler. The plugin does not intercept responses or throw.

```ts
import { Elysia } from 'elysia'
import { bearer } from '@elysia/bearer'

const app = new Elysia()
    .use(bearer())
    .get('/sign', ({ bearer }) => bearer)
```

--------------------------------

### Use bearer plugin in Elysia with beforeHandle

Source: https://github.com/elysiajs/elysia-bearer/blob/main/README.md

Example usage of the bearer plugin. It decorates the `bearer` context property and shows a `beforeHandle` hook that returns a 400 status with a `WWW-Authenticate` header when no token is provided.

```typescript
import { Elysia } from 'elysia'
import { bearer } from '@elysia/bearer'

const app = new Elysia()
    .use(bearer())
    .get('/sign', ({ bearer }) => bearer, {
        beforeHandle({ bearer, set }) {
            if (!bearer) {
                set.status = 400
                set.headers[
                    'WWW-Authenticate'
                ] = `Bearer realm='sign', error="invalid_request"`

                return 'Unauthorized'
            }
        }
    })
    .listen(8080)
```

--------------------------------

### Import paths for bearer and BearerOptions

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/types.md

Import paths for the bearer plugin and BearerOptions type. Use the package import for production, or the relative source import when working in the repository. Both import the same named exports.

```ts
import { bearer, type BearerOptions } from '@elysia/bearer'
// or, from the repository source:
import { bearer, type BearerOptions } from '../src' // src/index.ts
```

--------------------------------

### Default bearer() configuration

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/configuration.md

Uses the plugin with default RFC6750-compliant extractor settings: body key 'access_token', query key 'access_token', and header scheme 'Bearer'.

```ts
import { bearer } from '@elysia/bearer'

const app = new Elysia().use(bearer())
```

--------------------------------

### bearer(options?: BearerOptions) => Elysia

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/api-reference/bearer.md

Creates an Elysia plugin instance that derives a bearer token from the request. The token is extracted from the Authorization header (default prefix 'Bearer'), a query parameter (default 'access_token'), or the request body (default 'access_token'). The derived value is available as the 'bearer' property in handlers.

```APIDOC
## bearer(options?: BearerOptions) => Elysia

### Description
Creates an Elysia plugin instance that derives a bearer token from the request. The token is extracted from the Authorization header (default prefix 'Bearer'), a query parameter (default 'access_token'), or the request body (default 'access_token'). The derived value is available as the 'bearer' property in handlers.

### Method
Function call (plugin factory)

### Endpoint
N/A (plugin factory)

### Parameters
#### options (BearerOptions) - Optional
- **extract.body** (string) - Optional - Default: 'access_token' - The name of the body field to extract the token from.
- **extract.query** (string) - Optional - Default: 'access_token' - The name of the query parameter to extract the token from.
- **extract.header** (string) - Optional - Default: 'Bearer' - The prefix to look for in the Authorization header.

### Request Example
```ts
import { bearer } from '@elysiajs/bearer'

const app = new Elysia()
    .use(bearer())
    .get('/', ({ bearer }) => bearer)
```

### Response
#### Success Response (200)
- **bearer** (string) - The extracted bearer token, or undefined if not found.

#### Response Example
```json
{
  "bearer": "token-value"
}
```
```

--------------------------------

### BearerOptions

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/types.md

Configuration interface for customizing token extraction in the bearer plugin. Allows specifying body, query, and header field names for non-RFC6750 compliant APIs.

```APIDOC
## BearerOptions

### Description
Configuration interface for the bearer plugin, allowing customization of token extraction fields for APIs that do not comply with RFC6750.

### Fields

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `extract` | `{ body?: string; query?: string; header?: string }` | yes (the property must exist; the whole `extract` object is optional at the call site via default parameter) | Custom extractor settings for APIs that do not comply with RFC6750. |
| `extract.body` | `string` | no | Determined which field should be identified as the Bearer token. Default: `access_token`. **Runtime note:** in 1.4.4 this key is only written into the plugin `seed`; the derive logic never reads the request body, so this option has no extraction effect in the current implementation. |
| `extract.query` | `string` | no | The query parameter name identified as the Bearer token. Default: `access_token`. Read at request time via `query[queryName]`. |
| `extract.header` | `string` | no | The `Authorization` scheme type that should be treated as the Bearer token. Default: `Bearer`. Used as a prefix for `authorization.startsWith(header)` and stripped with `slice(header.length + 1)`. |

### Defaults

If `options` is omitted entirely, the default is the full object `{ extract: { body: 'access_token', query: 'access_token', header: 'Bearer' } }`. If `options` is provided without `extract`, the same defaults apply through the destructuring default.

### Import Paths

```ts
import { bearer, type BearerOptions } from '@elysia/bearer'
// or, from the repository source:
import { bearer, type BearerOptions } from '../src' // src/index.ts
```
```

--------------------------------

### Basic usage of @elysia/bearer

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/api-reference/bearer.md

Basic usage of the bearer plugin. It extracts the token from the Authorization header (RFC6750) or the `access_token` query parameter. If no credentials are provided, the `bearer` property is undefined.

```ts
import { Elysia } from 'elysia'
import { bearer } from '@elysia/bearer'

const app = new Elysia()
    .use(bearer())
    .get('/sign', ({ bearer }) => bearer)
    .listen(8080)

// GET /sign with header "Authorization: Bearer saltyAom"        -> 200 "saltyAom"
// GET /sign?access_token=saltyAom                               -> 200 "saltyAom"
// GET /sign with no credentials                                  -> 200 (body is undefined)
```

--------------------------------

### bearer() plugin factory source definition

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/api-reference/bearer.md

The exact source definition of the bearer() function from src/index.ts. It creates an Elysia instance with a global derive that provides a 'bearer' getter, extracting the token from the Authorization header or query parameter.

```typescript
export const bearer = (
	{
		extract: {
			body = 'access_token',
			query: queryName = 'access_token',
			header = 'Bearer'
		} = {
			body: 'access_token',
			query: 'access_token',
			header: 'Bearer'
		}
	}: BearerOptions = {
		extract: {
			body: 'access_token',
			query: 'access_token',
			header: 'Bearer'
		}
	}
) =>
	new Elysia({
		name: '@elysiajs/bearer',
		seed: {
			body,
			query: queryName,
			header
		}
	}).derive(
		{ as: 'global' },
		function deriveBearer({ query, headers: { authorization } }) {
			return {
				get bearer() {
					if ((authorization as string)?.startsWith(header))
						return (authorization as string).slice(
							header.length + 1
						)

					const q = query[queryName] as string | string[] | undefined

					if (Array.isArray(q)) return q[0]
					if (q) return q
				}
			}
		}
	)
```

--------------------------------

### Custom extraction and error handling with @elysia/bearer

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/api-reference/bearer.md

Custom extraction and error handling. Configure the plugin to read the token from a custom header, query, and body key (non-RFC6750). The `beforeHandle` hook returns a 400 status with a `WWW-Authenticate` header when the token is missing.

```ts
import { Elysia } from 'elysia'
import { bearer } from '@elysia/bearer'

const app = new Elysia()
    // non-RFC6750 API: read token from `Authorization: a <token>`,
    // query key `a`, and (config-seed only) body key `a`
    .use(
        bearer({
            extract: {
                body: 'a',
                header: 'a',
                query: 'a'
            }
        })
    )
    .get('/sign', ({ bearer }) => bearer, {
        beforeHandle({ bearer, set }) {
            if (!bearer) {
                set.status = 400
                set.headers['WWW-Authenticate'] =
                    `Bearer realm='sign', error="invalid_request"`

                return 'Unauthorized'
            }
        }
    })
    .listen(8080)

// GET /sign with "Authorization: a saltyAom" -> 200 "saltyAom"
// GET /sign?                         -> 400 "Unauthorized" + WWW-Authenticate header
```

--------------------------------

### Configure extract option for custom token extraction

Source: https://github.com/elysiajs/elysia-bearer/blob/main/README.md

Configuration type for the `extract` option, allowing custom token extraction fields for non-RFC6750 compliant APIs. Defaults: `body` and `query` to `access_token`, `header` to `Bearer`.

```typescript
/**
 * If the API doesn't compliant with RFC6750
 * The key for extracting the token is configurable
 */
extract: {
    /**
     * Determined which fields to be identified as Bearer token
     *
     * @default access_token
     */
    body?: string
    /**
     * Determined which fields to be identified as Bearer token
     *
     * @default access_token
     */
    query?: string
    /**
     * Determined which type of Authentication should be Bearer token
     *
     * @default Bearer
     */
    header?: string
}
```

--------------------------------

### Custom extractor keys for bearer()

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/configuration.md

Configures custom extractor keys for body, header, and query. Note that the body key is declared but not read by the extraction logic in version 1.4.4.

```ts
import { bearer } from '@elysia/bearer'

const app = new Elysia().use(
    bearer({
        extract: {
            body: 'a',
            header: 'a',
            query: 'a'
        }
    })
)
```

--------------------------------

### Partial extractor override with bearer()

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/configuration.md

Overrides only the body extractor key to 'token'; the query and header keys retain their defaults ('access_token' and 'Bearer') because per-property defaults apply.

```ts
import { bearer } from '@elysia/bearer'

// query key stays 'access_token', header stays 'Bearer'
const app = new Elysia().use(
    bearer({
        extract: {
            body: 'token'
        }
    })
)
```

--------------------------------

### bearer() — Plugin Factory

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/api-reference/index.md

The bearer() function is the main export of the @elysia/bearer package. It returns a new Elysia instance that decorates the 'bearer' property onto the request Context for all scopes. This plugin extracts a Bearer token from the Authorization header or query parameter according to RFC6750.

```APIDOC
## bearer()

### Description
Creates a new Elysia plugin instance that decorates the `bearer` property onto the request `Context`. The plugin extracts a Bearer token from the incoming request per RFC6750 and makes it available as `context.bearer`. It does not perform authentication or validation.

### Method
N/A (Plugin factory function)

### Endpoint
N/A (Elysia plugin)

### Parameters
#### Options (BearerOptions)
- **header** (string) - Optional - The keyword used to identify the Authorization header scheme. Defaults to `'Bearer'`.
- **query** (string) - Optional - The query parameter name to read the token from. Defaults to `'access_token'`.

### Request Example
```ts
import { Elysia } from 'elysia'
import { bearer } from '@elysia/bearer'

const app = new Elysia()
    .use(bearer())
    .get('/sign', ({ bearer }) => bearer)
```

### Response
#### Success Response
- **bearer** (string | undefined) - The extracted Bearer token, or `undefined` if no token is present.

#### Response Example
```ts
// In a route handler, the `bearer` property is available on the context.
// Example: GET /sign with Authorization: Bearer my-token
// Returns: 'my-token'
```

### Notes
- The plugin does not validate the token; it only extracts it.
- Extraction precedence: Authorization header first, then query parameter.
- If the header value is empty after stripping the keyword and space, it returns an empty string (falsy).
- If the query parameter value is an array, the first element is used.
- The plugin is installed globally (`as: 'global'`), so the `bearer` property is available in all handlers and hooks.
```

--------------------------------

### bearer (context accessor)

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/types.md

The derived getter for the bearer token on the context object, returning the extracted token as a string or undefined.

```APIDOC
## bearer (context accessor)

### Description
The `bearer` property on the context object, derived from the plugin, provides the extracted token as a string or undefined.

### Type

`string | undefined`

### Behavior

- `string` — token extracted from the `Authorization` header (after stripping the configured scheme and one following character) or from the configured query key (first element when repeated).
- `undefined` — when no matching header and no matching query parameter exist.

An empty header token (`Authorization: "Bearer "`) yields `''` — a `string`, but falsy.

### Usage

Available on any handler/hook `Context` after `.use(bearer())`.

### Import Paths

```ts
import { bearer } from '@elysia/bearer'
// or, from the repository source:
import { bearer } from '../src' // src/index.ts
```
```

--------------------------------

### BearerOptions type definition

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/api-reference/bearer.md

The BearerOptions object type, expanded from its alias. It shows the optional fields for body, query, and header with their default values.

```typescript
{
	extract: {
		body?: string   // @default 'access_token'
		query?: string  // @default 'access_token'
		header?: string // @default 'Bearer'
	}
}
```

--------------------------------

### BearerOptions interface definition

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/types.md

The exact source definition of the BearerOptions interface from src/index.ts:3-28. It defines the extract object with optional body, query, and header fields, each defaulting to 'access_token' or 'Bearer' respectively. The extract object is optional at the call site via default parameter, but the property must exist when provided.

```ts
export interface BearerOptions {
	description: string;
	extract: {
		/**
		 * Determined which fields to be identified as Bearer token
		 *
		 * @default access_token
		 */
		body?: string
		/**
		 * Determined which fields to be identified as Bearer token
		 *
		 * @default access_token
		 */
		query?: string
		/**
		 * Determined which type of Authentication should be Bearer token
		 *
		 * @default Bearer
		 */
		header?: string
	}
}
```

--------------------------------

### Inferred bearer accessor type

Source: https://github.com/elysiajs/elysia-bearer/blob/main/_autodocs/types.md

The inferred type of the context.bearer property, which is string | undefined. It is derived from the plugin's derive function body (src/index.ts:58-72) and not a named type. The string value is the token extracted from the Authorization header or query parameter; undefined when neither is present.

```ts
// inferred value of context.bearer
string | undefined
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.