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

# API Tokens

Bijection component for API token management: issuance, validation, rotation, revocation, and encrypted third-party key storage

- Package: @bijectionhq/api-tokens
- Category: Authentication
- Status: Preview
- License: MIT
- Bijection source (repository access required): https://github.com/bijectionhq/api-tokens/tree/6e0fe40862cf61af1661cd987bfb7a35cdf200ae
- Upstream: https://github.com/TimpiaAI/convex-api-tokens/tree/4c04e42369797d0fa55310e810864a45396a1e8f
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/api-tokens

## Get the source

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

```sh
git clone https://github.com/bijectionhq/api-tokens.git
cd api-tokens
git checkout 6e0fe40862cf61af1661cd987bfb7a35cdf200ae
```

## 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 convex-api-tokens. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# API Tokens

## Instructions

A Convex component that provides complete API token lifecycle management for SaaS applications. Issue sk_-prefixed tokens with namespaces, expiration, and metadata, then validate them on incoming requests. Includes token rotation, bulk revocation, encrypted third-party key storage with AES-256-GCM, and HTTP/mutation middleware for protecting endpoints.

### Installation

```bash
npm install convex-api-tokens
```

## Use cases

- **Building a SaaS API**: Issue API keys to customers with scopes, expiration, and per-user namespacing for multi-tenant access control
- **Securing webhook endpoints**: Use `createTokenAuth()` HTTP middleware to validate tokens on incoming webhook requests with detailed failure reasons
- **Managing third-party credentials**: Store encrypted Stripe, OpenAI, or other API keys per user/organization with automatic server-side encryption
- **Token rotation workflows**: Implement security best practices by programmatically refreshing tokens while preserving metadata and audit trails
- **Admin dashboards**: List and revoke user tokens by namespace, time range, or individual token without exposing raw token values

## How it works

The component uses SHA-256 hashing to store tokens securely without persisting raw values, generating `sk_`-prefixed tokens with displayable prefixes for UI purposes. You register the component in `convex.config.ts` and create an `ApiTokens` client instance to access methods like `create()`, `validate()`, and `invalidate()` from your mutations and queries.

For authentication, the `withTokenAuth()` mutation middleware automatically validates tokens from function arguments and passes auth context to your handler, while `createTokenAuth()` provides HTTP endpoint protection. The component supports TypeScript generics for typed metadata and includes automatic cleanup via the `cleanup()` method for scheduled garbage collection.

Third-party key storage uses AES-256-GCM encryption with PBKDF2 key derivation, requiring an `API_TOKENS_ENCRYPTION_KEY` environment variable. The component maintains complete isolation through Convex's component system, ensuring your application code cannot accidentally access internal token tables.

## 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 API Tokens is not needed

## Resources

- [npm package](https://www.npmjs.com/package/convex-api-tokens)
- [GitHub repository](https://github.com/TimpiaAI/convex-api-tokens)
- [Live demo](https://api-tokens-demo.vercel.app/)
- [Convex Components Directory](https://www.convex.dev/components/convex-api-tokens)
- [Convex documentation](https://docs.convex.dev)