> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skybridge.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Verifier

> Validate access tokens for the bearer-auth middleware

A verifier is the provider-specific token check you implement and pass to [`requireBearerAuth`](https://docs.skybridge.tech/api-reference/require-bearer-auth) or [`optionalBearerAuth`](https://docs.skybridge.tech/api-reference/optional-bearer-auth). The middleware calls it on each request to validate the bearer token before any [tool](https://docs.skybridge.tech/build/tools.md) runs.

## Example

`verifyAccessToken` validates the token however your provider requires, returns an `AuthInfo` for a valid token, and throws `OAuthError` otherwise. Pass it to the middleware as `verifier: { verifyAccessToken }`.

```ts theme={null}
import { type AuthInfo, OAuthError } from "skybridge/server";

async function verifyAccessToken(token: string): Promise<AuthInfo> {
  try {
    const payload = await validateToken(token); // JWT verification, introspection, etc.
    return {
      token,
      clientId: payload.client_id,
      scopes: payload.scope.split(" "),
      expiresAt: payload.exp,
      extra: { subject: payload.sub },
    };
  } catch (err) {
    throw new OAuthError(
      "invalid_token",
      err instanceof Error ? err.message : "Token validation failed",
    );
  }
}
```

> [!NOTE]
>
> How you validate the token depends on your provider. Check its docs.

## `verifyAccessToken`

```ts theme={null}
verifyAccessToken(token: string): Promise<AuthInfo>;
```

The verifier's only required method.

* Resolve with an `AuthInfo` for a valid token. The middleware puts it on `extra.http?.authInfo` for tool [handlers](https://docs.skybridge.tech/api-reference/register-tool.md#handler).
* Throw `OAuthError("invalid_token", message)` for a malformed, badly signed, or expired token. The middleware returns a 401 with the right `WWW-Authenticate` header.

Do not check scopes here: the middleware enforces `requiredScopes` against `authInfo.scopes` and returns a 403 on a missing scope.

## `createJwksVerifier`

```ts theme={null}
createJwksVerifier<TExtra>(config: { issuer: string; audience?: string; jwksUri?: string }): TokenVerifier<TExtra>;
```

Builds a verifier that validates JWTs against a remote JWKS. The [providers](https://docs.skybridge.tech/guides/auth-providers.md) use it internally; call it yourself when hand-building an [`OAuthConfig`](https://docs.skybridge.tech/api-reference/custom-provider#returns). `jwksUri` defaults to `${issuer}/.well-known/jwks.json`, and omitting `audience` skips the audience check, for IdPs that bind none.

Verified claims land in `extra` with `sub` renamed to `subject`, while `client_id`, `scope` and `exp` become `AuthInfo` fields.

## `AuthInfo`

What `verifyAccessToken` resolves with for a valid token.

```ts theme={null}
type AuthInfo = {
  token: string;
  clientId: string;
  scopes: string[];
  expiresAt: number;
  extra?: Record<string, unknown>;
};
```

| Field | Purpose |
| - | - |
| `token` | The raw bearer token. |
| `clientId` | The OAuth `client_id`, often the `azp` or `client_id` claim. |
| `scopes` | The scopes granted, checked against `requiredScopes` and per-tool [`securitySchemes`](https://docs.skybridge.tech/api-reference/register-tool#securityschemes). |
| `expiresAt` | Expiry in unix seconds. Required: tokens with no expiration are rejected. |
| `extra` | Anything else you want available to handlers, for example `subject` or `email`. |

`extra` is an untyped bag by default. Pass the claims your verifier resolves with (`Promise<AuthInfo<Claims>>`) and handlers receive that shape, since the type travels with the verifier into the server.

> [card] [requireBearerAuth](https://docs.skybridge.tech/api-reference/require-bearer-auth.md)
>
> Require a token on every request

> [card] [optionalBearerAuth](https://docs.skybridge.tech/api-reference/optional-bearer-auth.md)
>
> Accept a token when present, allow anonymous otherwise

> [card] [Authenticate Users](https://docs.skybridge.tech/build/auth.md)
>
> Add sign-in to your app end to end


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.