@x12i/authx-token-openapi

OpenAPI 3.1 contract for the AuthX Token Infrastructure HTTP API, with component schemas generated from @x12i/authx-token-types.

Part of the AuthX monorepo. See the root README for API usage examples.

Install

npm install @x12i/authx-token-openapi @x12i/authx-token-types

Exports

| Import path | Contents | | --- | --- | | @x12i/authx-token-openapi | Merged spec object + types | | @x12i/authx-token-openapi/openapi.json | Raw base OpenAPI JSON file |

Usage

Load the full spec (paths + schemas)

import { authxOpenApiSpec } from "@x12i/authx-token-openapi";

// authxOpenApiSpec.paths — all routes
// authxOpenApiSpec.components.schemas — Zod-derived JSON Schemas
console.log(authxOpenApiSpec.info.title);

Base spec without merged schemas

import { authxOpenApiBase } from "@x12i/authx-token-openapi";

Raw JSON file

import spec from "@x12i/authx-token-openapi/openapi.json" with { type: "json" };

Or read from disk after install:

node_modules/@x12i/authx-token-openapi/openapi.json

API surface

Default server: http://localhost:3100

| Method | Path | Summary | | --- | --- | --- | | GET | /health | Health check | | GET | /v1/apps | List apps | | POST | /v1/apps | Create app | | PATCH | /v1/apps/{appId} | Update app | | POST | /v1/tokens/issue | Issue token | | POST | /v1/tokens/verify | Verify token | | POST | /v1/tokens/decrypt | Decrypt encrypted token | | POST | /v1/tokens/introspect | Introspect token | | POST | /v1/tokens/revoke | Revoke token(s) | | GET | /v1/tokens | List tokens | | GET | /v1/tokens/{tokenId} | Get token | | GET | /v1/audit | List audit events |

Security scheme (when AUTHX_API_KEY is configured on the service):

ApiKeyAuth:
  type: apiKey
  in: header
  name: x-authx-api-key

Component schemas

Merged from @x12i/authx-token-types/json-schema:

| Schema | Type | | --- | --- | | AuthxTokenPayload | Decoded token payload | | AuthxTokenIssueRequest | Issue request body | | AuthxTokenVerifyRequest | Verify/decrypt/introspect body | | AuthxTokenRevokeRequest | Revoke request body | | AuthxAppDescriptor | App metadata | | AuthxAppCreateRequest | Create app body |

TypeScript helper

import type { AuthxApiPaths } from "@x12i/authx-token-openapi";

type HealthPath = AuthxApiPaths; // keyof paths object

Use with OpenAPI codegen tools (e.g. openapi-typescript, @hey-api/openapi-ts) by pointing at openapi.json or the merged authxOpenApiSpec.

Example: generate client types

npx openapi-typescript node_modules/@x12i/authx-token-openapi/openapi.json -o authx-api.d.ts

For full schemas, export the merged spec to a file in your build step:

import { writeFileSync } from "node:fs";
import { authxOpenApiSpec } from "@x12i/authx-token-openapi";

writeFileSync("authx-openapi.json", JSON.stringify(authxOpenApiSpec, null, 2));

Development

npm run build -w @x12i/authx-token-openapi
npm test -w @x12i/authx-token-openapi

When adding API routes, update:

1. openapi.json — paths and metadata
2. @x12i/authx-token-types — Zod schemas (auto-flows to JSON Schema)

Source: src/index.ts.

Related packages

| Package | Role | | --- | --- | | @x12i/authx-token-types | Source of truth for schemas | | @x12i/authx-token-service | Implements this contract | | @x12i/authx-token-cli | CLI client |

See also docs/api.md.