---
name: bijection-tokens
description: "Evaluate and integrate the Tokens component with Bijection."
---

# Tokens

Hashed-secret token primitive with mint-once, TTL, revoke and scope, as a Bijection component

- Package: @bijectionhq/tokens
- Category: Authentication
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/tokens/tree/12601a7a9cfb983b9f28181b0f8bd608726be735
- Upstream: https://github.com/vllnt/convex-tokens/tree/1581eb60769ce391697bf1d5ae243a2a961f1040
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/tokens

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/tokens.git
cd tokens
git checkout 12601a7a9cfb983b9f28181b0f8bd608726be735
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes @vllnt/convex-tokens. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


> Agents: read this skill fully before writing code that uses Secret Tokens. Follow the installation and configuration steps exactly.

# Secret Tokens

## Instructions

@vllnt/convex-tokens provides an expiring secret-token primitive backed by isolated Convex tables. Mint a token against an optional opaque resource reference, return the raw value once, and persist its digest instead of the secret.

mint returns the raw token and its ID. validate checks validity in a scope, and revoke invalidates a token. TTLs are enforced with server time. list and getMetadata expose management information without the token hash, while cleanup removes eligible expired records.

Your host owns authentication, delivery, access policy, and abuse protection. Mint-once means the raw secret is shown once; validation does not consume the token. Flows requiring single-use redemption need atomic host-side coordination. Never log or persist the raw token in your UI.

Maintained by [bntvllnt](https://bntvllnt.com) at [VLLNT](https://vllnt.com). Find the author on [GitHub](https://github.com/bntvllnt) and [X](https://x.com/bntvllnt).

### Installation

```bash
npm install @vllnt/convex-tokens
```

Current npm version: `@vllnt/convex-tokens@0.1.0`

## Use cases

- Resource sharing: issue a time-limited link to a host-authorized resource.
- Account flows: use a token as one part of an email-verification or recovery flow designed by your backend.
- Device or integration setup: associate a temporary token with a pending host-side setup record.
- Temporary access: validate a scoped token and revoke it before its expiry.

## How it works

mint returns the raw token and its ID. validate checks validity in a scope, and revoke invalidates a token. TTLs are enforced with server time. list and getMetadata expose management information without the token hash, while cleanup removes eligible expired records.

Your host owns authentication, delivery, access policy, and abuse protection. Mint-once means the raw secret is shown once; validation does not consume the token. Flows requiring single-use redemption need atomic host-side coordination. Never log or persist the raw token in your UI.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by Secret Tokens is not needed

## Resources

- [npm package](https://www.npmjs.com/package/%40vllnt%2Fconvex-tokens)
- [GitHub repository](https://github.com/vllnt/convex-tokens)
- [Live demo](https://vllnt.com/)
- [Convex Components Directory](https://www.convex.dev/components/vllnt/convex-tokens)
- [Convex documentation](https://docs.convex.dev)