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

# API Keys

Application API key lifecycle

- Package: @bijectionhq/api-keys
- Category: Authentication
- Status: Preview
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/api-keys/tree/9a2b355a7bf6dfcf507a348ca5dfa581a083fdc1
- Upstream: https://github.com/gaganref/convex-api-keys/tree/207b49db4c29bb943831da682c6ce617ed38cdc4
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/api-keys

## Get the source

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

```sh
git clone https://github.com/bijectionhq/api-keys.git
cd api-keys
git checkout 9a2b355a7bf6dfcf507a348ca5dfa581a083fdc1
```

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


# Convex Api Keys

## Instructions

A Convex component that provides secure API key management with automatic expiry, idle timeout tracking, and typed permissions. Handles key creation, validation, rotation, and revocation with SHA-256 hash storage and comprehensive audit logging. Includes built-in cron jobs for automatic cleanup and expiry sweeping.

### Installation

```bash
npm install convex-api-keys
```

## Use cases

• **Backend service authentication** - Generate API keys for server-to-server communication with scoped permissions like `read`, `write`, `admin`
• **Multi-tenant API access** - Use namespaced keys to isolate different environments or customers (e.g., `acme:production` vs `acme:testing`)
• **Security compliance workflows** - Implement key rotation policies with audit trails, automatic expiry, and idle timeout enforcement
• **Rate limiting and access control** - Validate API keys in HTTP actions and track usage patterns with metadata and permissions
• **Dashboard key management** - Build admin interfaces with paginated key listing, revocation, and event history

## How it works

The component stores only SHA-256 hashes of API keys, never plaintext tokens, and returns the actual token only once during creation or rotation. You instantiate an `ApiKeys` client with optional TypeScript generics for compile-time type safety on namespaces, permissions, and metadata shapes.

Key operations like `create()`, `validate()`, `refresh()`, and `invalidate()` work through Convex mutations and queries. The `validate()` function is read-only for performance, while `touch()` separately updates the `lastUsedAt` timestamp for idle timeout tracking. Built-in cron jobs automatically sweep expired and idle keys every hour.

The component includes comprehensive audit logging through `listEvents()` and supports bulk operations like `invalidateAll()` for security rotations. You can register `onInvalidate` hooks to trigger custom logic when keys are revoked, and configure defaults for prefixes, TTL, and idle timeouts during instantiation.

## 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 Convex Api Keys is not needed

## Resources

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