@unkey/api

@unkey/api is the official, Speakeasy-generated TypeScript SDK for Unkey’s API key management and rate-limiting platform. It gives Node.js, browser, and edge-runtime applications a fully typed client for creating and verifying API keys, enforcing rate limits, managing permissions and roles, and querying usage analytics — all through a single Unkey client instance authenticated with a root key.

Every request and response is validated against Zod schemas generated directly from Unkey’s OpenAPI spec, so breaking API changes surface as TypeScript compile errors rather than runtime surprises. The SDK ships with built-in retry policies, async-iterable pagination, tree-shakeable standalone functions for bundle-size-sensitive environments, and a pluggable HTTP client for proxying or mocking requests in tests.

What You Get

• A single Unkey client class exposing keys, apis, ratelimit, identities, permissions, projects, deployments, domains, environments, gateway, portal, and analytics resources
• Zod-validated request/response models generated from Unkey’s OpenAPI spec, catching schema drift at compile time
• Tree-shakeable standalone functions (e.g. keysVerifyKey) for bundle-size-conscious serverless and edge deployments
• Built-in async-iterable pagination for list endpoints
• Configurable retry strategies (backoff or none) settable globally or per-call
• A pluggable HTTPClient wrapper around fetch for injecting proxies, custom headers, or test fixtures

Common Use Cases

• Verifying an incoming request’s API key and permissions before processing it
• Creating and rotating API keys for a multi-tenant SaaS product
• Applying and overriding rate limits per customer or endpoint
• Querying gateway request and verification analytics for usage dashboards
• Managing workspace identities, roles, and permission grants programmatically

Under The Hood

Architecture core.ts is a minimal re-export hub; the actual client lives in src/sdk/sdk.ts as a Unkey class extending ClientSDK, lazily instantiating one resource class per API surface (Analytics, Apis, Apps, Keys, Ratelimit, Identities, Permissions, Portal, Projects, Deployments, Domains, Environments, Gateway, Github, Internal) via getters. Each resource method delegates to a same-named function under src/funcs/ (one file per endpoint, e.g. keysVerifyKey.ts), which builds the HTTP request, calls through the shared UnkeyCore client, and parses the response against generated Zod schemas in src/models/. Cross-cutting concerns — retries, auth header injection, URL templating, response matching — live in src/lib/ (retries.ts, security.ts, url.ts, http.ts, schemas.ts) and are composed into every func rather than duplicated per endpoint. This one-func-per-endpoint-plus-shared-lib pattern is the standard Speakeasy SDK generation architecture, and the whole tree is regenerated from an OpenAPI spec rather than hand-maintained.

Tech Stack TypeScript, published via tshy (dual ESM/CJS build with hand-authored conditional exports for the root, ./types, ./models/errors, ./models/components, ./models/operations, plus a wildcard passthrough), validated at runtime with zod (a peer-agnostic ^3 or ^4 range), linted with ESLint and typescript-eslint, and built on the native Fetch API through a custom HTTPClient wrapper rather than axios or another request library. No web framework or ORM is involved — this is a pure API client package with zod as its only runtime dependency.

Code Quality No test files exist anywhere in the package’s source tree — its CONTRIBUTING guide explicitly states the code is Speakeasy-generated and manual pull requests to internal files are rejected, so quality is enforced upstream in the generator rather than via a local test suite. What is present is comprehensive: every exported error type is a typed subclass of UnkeyError carrying status code, headers, body, and the raw response; every function’s documentation covers required permissions, common use cases, and status-code-specific error conditions; naming is consistent across all operations (resource-plus-verb-plus-noun); and dedicated validation-error types give explicit, typed failure modes for schema drift instead of silent untyped casts.

API Design The public surface groups dozens of operations under more than a dozen resource namespaces on a single Unkey client (e.g. unkey.keys.verifyKey(...)), with each method also exported as a tree-shakeable standalone function for bundle-size-sensitive edge and serverless use. Getting started requires only a root key and one import; retries, pagination as async iterables on list responses, and HTTP client customization (proxy agents, request/response hooks) are all opt-in extensions layered onto that same simple entry point rather than required boilerplate.