# 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.

## Operations

Scope: none

- [Mint a token](./access-tokens/create.md) — `POST /v1/infra/servers/:id/access-tokens`
- [Refresh a token](./access-tokens/refresh.md) — `POST /v1/infra/servers/:id/access-tokens/:tokenId/refresh`
- [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`
- [Sign a resource URL](./access-tokens/resource-url.md) — `POST /v1/infra/servers/:id/access-tokens/:tokenId/resource-url`

## Availability

The section is enabled on the platform side, and it may be switched off for a given Bitrix24 account. The pre-call signal is the `available` field of the `data.capabilities.servers.preview` block in the [`GET /v1/me`](/docs/keys-auth/me) response:

| `available` | What it means |
|-------------|---------------|
| `true` | All section operations are enabled; key permissions still apply |
| `false`, accompanied by `reason: "FEATURE_DISABLED"` | Access tokens are not usable for this key. When the section is switched off on the platform, each operation returns `503 FEATURE_DISABLED`; if mint passed the preliminary check before the switch, the fresh transactional check returns `403 FEATURE_DISABLED` |

The same signal arrives in the `data.infra.preview` block — it is present even when the key is not bound to a Bitrix24 account and the response therefore carries no `data.capabilities` block. The `data.deployment` block carries no `preview` field at all for Cowork keys, so do not rely on it as the only signal. A platform administrator switches the section on — an API call cannot do it.

While the section is off, the closest available deploy check is the `data.steps[]` array of the [`POST /v1/infra/servers/:id/deploy`](/docs/infra/deploy/deploy) response, where every step carries a `status` field with the values `ok`, `warning` and `error`. The `healthcheck` step confirms that the application responds on its port. The `tunnel_routing` step confirms that the Gateway tunnel points at that port — a Galaxy application has no such step. Neither step exercises the public route with authorization at its entry point, which remains a property of the `api-bearer` mode.

## 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. If the check runs longer than 10 minutes — [`POST /access-tokens/:tokenId/refresh`](./access-tokens/refresh.md) issues a fresh JWT for the same record.
4. [`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.

`api-bearer` confirms the request is made by the key owner, but does not create a Bitrix24 user session — an application route that needs a verified administrator via `X-Vibe-Authorization` and `GET /v1/me` will get `currentUser: null` for requests made with an `api-bearer` token. See [Mint a token](./access-tokens/create.md) and [What the app receives](/docs/infra/app-runtime).

**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, and 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)