# Auth

> Call your miniapp's backend as the signed-in Glassly user.

Source: https://docs.glassly.ai/app-devs/core-concepts/auth/

If your miniapp has its own backend, `session.auth` lets you call it as the
current Glassly user, with no login screen. The host hands your miniapp a signed
token; your backend verifies it and gets the user's id. Two steps.

## Get started

### 1. Call your backend from the miniapp

Use `session.auth.fetch` exactly like `fetch`. It attaches the user's token for
you.

```typescript src/background/index.ts
const res = await session.auth.fetch("https://api.example.com/notes");
const notes = await res.json();
```

### 2. Verify the token on your backend

Install [`@glassly/auth`](https://www.npmjs.com/package/@glassly/auth) and add its
middleware. The verified user lands on the request.

```typescript
import { createAuthService, type AuthVariables } from "@glassly/auth";
import { Hono } from "hono";

const auth = createAuthService({ packageName: "com.example.myapp" });

const app = new Hono<{ Variables: AuthVariables }>();
app.use("/api/*", auth.hono());

app.get("/api/notes", (c) => {
  const { userId } = c.get("auth");
  return c.json({ userId: userId });
});
```

That's it. Every request to `/api/*` now arrives with a verified Glassly user id,
and a token minted for another miniapp can't be used against yours (its audience
is pinned to your package).

## On the client

`session.auth.fetch(input, init)` is the easy path. If you bring your own HTTP
client, grab the header or token instead:

| Method | Returns | Description |
|---|---|---|
| `fetch(input, init?)` | `Promise<Response>` | Standard `fetch` with the `Authorization` header added. |
| `getAuthHeader(options?)` | `Promise<string>` | The string `"Bearer <token>"`. |
| `getToken(options?)` | `Promise<string>` | The raw token. |
| `onUpdate(handler)` | `() => void` | Fires when the host rotates the token. Returns an unsubscribe function. |

```typescript
const header = await session.auth.getAuthHeader();
await axios.get("https://api.example.com/notes", { headers: { Authorization: header } });
```

The token rotates, so read it through `fetch`/`getAuthHeader`/`getToken` each time
rather than caching the string. Those three take a `minTtlMs` option, the minimum
lifetime the token must still have (default `30000`); if the current token has
less left, the call waits for the next refresh.

```typescript
const res = await session.auth.fetch("https://api.example.com/sync", { minTtlMs: 120_000 });
```

`session.auth.current` holds the active token and who it's for (or `null` before
the host issues one). `session.auth.userId` and `session.auth.oemId` are
getter shortcuts.

| Field | Type | Description |
|---|---|---|
| `userId` | `string` | The Glassly user this token is for. |
| `oemId` | `string \| undefined` | The OEM that provisioned the user, when present. |
| `token` | `string` | The signed token sent to your backend. |
| `expiresAt` | `number` | Expiry as a Unix timestamp in milliseconds. |

## On your backend

`createAuthService({ packageName })` checks the signature against Glassly's JWKS,
the issuer, and the audience (your `packageName`), and rejects expired tokens.
`packageName` can also come from the `MINIAPP_PACKAGE_NAME` environment variable.

Not on Hono? Verify directly:

```typescript
await auth.verifyRequest(request);        // a Web Request
await auth.verifyAuthHeader(headerValue); // an Authorization header value
await auth.verifyToken(token);            // a bare token
```

Each resolves to a `VerifiedAuth` (or throws `AuthError`):

| Field | Type | Description |
|---|---|---|
| `userId` | `string` | The Glassly user (the JWT `sub`). |
| `tenantId` | `string?` | The tenant that provisioned the user, when present. |
| `packageName` | `string` | Your miniapp package (the verified audience). |
| `tokenId` | `string?` | The token's `jti`, if set. |
| `expiresAt` | `number?` | `exp`, in Unix seconds. |
| `issuedAt` | `number?` | `iat`, in Unix seconds. |
| `claims` | `JWTPayload` | The raw verified claims. |

### Pointing at a non-production Core

A miniapp token is signed by exactly one Glassly environment, so by default
verification tries every environment's JWKS endpoint in order (production,
staging, dev, debug) and accepts the first one whose key validates the
signature. For local or self-hosted Core, pass a single `jwksUrl` (or set
`MINIAPP_AUTH_JWKS_URL`), which disables the fallback list and tries only that
URL:

```typescript
const auth = createAuthService({
  packageName: "com.example.myapp",
  jwksUrl: "http://localhost:3000/.well-known/jwks.json",
});
```

To try an explicit ordered list of endpoints instead of the built-in one, pass
`jwksUrls` (or set `MINIAPP_AUTH_JWKS_URLS` to a comma-separated list). It
takes precedence over `jwksUrl`.
