# Access tokens

Short-lived tokens for external access to a deployed application on a BLACKHOLE server. Two modes: `api-bearer` — JWT for the `Authorization` HTTP header, `share-url` — a distributable link with cookie authentication.

Scope: `vibe:infra`

## Operations

- [Mint a token](./access-tokens/create.md) — `POST /v1/infra/servers/:id/access-tokens`
- [List tokens](./access-tokens/list.md) — `GET /v1/infra/servers/:id/access-tokens`
- [Revoke a token](./access-tokens/delete.md) — `DELETE /v1/infra/servers/:id/access-tokens/:tokenId`

## Scenarios

**E2E deploy check via the public path:**

The `api-bearer` mode lets you confirm that requests travel through the real `nginx → Gateway → tunnel → application` route. An `exec + curl 127.0.0.1:3000` call checks only localhost and never touches the Gateway layer.

1. [`POST /access-tokens`](./access-tokens/create.md) with `mode: "api-bearer"`, `ttlSeconds: 600`.
2. Run the application's key endpoints with the `Authorization: Bearer <token>` header.
3. [`DELETE /access-tokens/:tokenId`](./access-tokens/delete.md) — revoke after the check.

If Bearer returns 502 while `exec + curl 127.0.0.1:3000` succeeds, the problem is in the Gateway or the tunnel, not in the application.

**Link for external viewing:**

1. [`POST /access-tokens`](./access-tokens/create.md) with `mode: "share-url"` and the desired `ttlSeconds`.
2. Pass the `url` field from the response to the recipient — the first visit sets a cookie, subsequent requests work without the `?s=` parameter.
3. If needed: [`DELETE /access-tokens/:tokenId`](./access-tokens/delete.md) to revoke early.

## See also

- [Deploy API](/docs/infra/deploy)
- [Access and modes](/docs/infra/access)
- [Infrastructure](/docs/infra)