AUTHZED_TOKEN=t_your_token_here_1234567deadbeef
AUTHZED_ENDPOINT=grpc.authzed.com:443

5. Import from the block's entry point:

import { v1, protobuf, deadlineInterceptor } from "./authzed/index.js";

Public API

v1.NewClient

function NewClient(
  token: string,
  endpoint?: string,
  security?: ClientSecurity
): ZedClientInterface

Creates a combined gRPC client that merges PermissionsService, SchemaService, WatchService, ExperimentalService, and Materialize services into a single object. The .promises property on the returned client exposes promisified versions of all unary and streaming methods. Use this for standard cloud-connected Authzed usage with TLS.

v1.NewClientWithCustomCert

function NewClientWithCustomCert(
  token: string,
  endpoint: string,
  cert: Buffer
): ZedClientInterface

Same as NewClient but accepts a PEM-encoded CA certificate Buffer for mutual TLS or self-signed cert scenarios. Use this when connecting to a self-hosted SpiceDB instance with a custom certificate authority.

v1.ClientSecurity

enum ClientSecurity {
  SECURE,
  INSECURE_LOCALHOST_ALLOWED,
  INSECURE_PLAINTEXT_CREDENTIALS,
}

Controls the channel credential strategy passed to the gRPC channel. Pass INSECURE_LOCALHOST_ALLOWED during local development against a SpiceDB instance running without TLS. Never use insecure modes in production.

deadlineInterceptor

function deadlineInterceptor(
  options: InterceptorOptions,
  nextCall: NextCall
): InterceptingCall

A gRPC client interceptor that automatically sets a deadline on every outbound call (default 30 seconds). Import directly from index.ts or util.ts and pass it to the interceptors array in your gRPC CallOptions. Prevents calls from hanging indefinitely when the server is unreachable.

ZedClientInterface

type ZedClientInterface = ZedDefaultClientInterface & {
  promises: ZedPromiseClientInterface;
};

The type returned by NewClient. The top-level properties are raw callback-based gRPC methods. The .promises sub-object exposes promisified equivalents suitable for async/await. Prefer .promises in application code.

Working examples

Scenario - Check a permission

Verify whether a user has a specific permission on a resource. This is the most common operation; call it on every authorization decision in your request handler.

import { v1 } from "./authzed/index.js";

const client = v1.NewClient(
  process.env.AUTHZED_TOKEN!,
  process.env.AUTHZED_ENDPOINT ?? "grpc.authzed.com:443"
);

async function canEditPost(userId: string, postId: string): Promise<boolean> {
  const request = v1.CheckPermissionRequest.create({
    resource: v1.ObjectReference.create({ objectType: "blog/post", objectId: postId }),
    permission: "edit",
    subject: v1.SubjectReference.create({
      object: v1.ObjectReference.create({ objectType: "blog/user", objectId: userId }),
    }),
  });

  const response = await client.promises.checkPermission(request);
  return (
    response.permissionship ===
    v1.CheckPermissionResponse_Permissionship.HAS_PERMISSION
  );
}

Scenario - Write a relationship

Persist a new relationship tuple (e.g. grant a user the "member" role on a team). Call this when your application's data model changes in a way that affects authorization.

import { v1 } from "./authzed/index.js";

const client = v1.NewClient(process.env.AUTHZED_TOKEN!, "grpc.authzed.com:443");

async function addTeamMember(teamId: string, userId: string): Promise<void> {
  const update = v1.RelationshipUpdate.create({
    operation: v1.RelationshipUpdate_Operation.CREATE,
    relationship: v1.Relationship.create({
      resource: v1.ObjectReference.create({ objectType: "team", objectId: teamId }),
      relation: "member",
      subject: v1.SubjectReference.create({
        object: v1.ObjectReference.create({ objectType: "user", objectId: userId }),
      }),
    }),
  });

  await client.promises.writeRelationships(
    v1.WriteRelationshipsRequest.create({ updates: [update] })
  );
}

Scenario - Local development with insecure SpiceDB

Connect to a locally running SpiceDB instance (e.g. via Docker) without TLS. Use ClientSecurity.INSECURE_LOCALHOST_ALLOWED and point at the local port.

import { v1 } from "./authzed/index.js";

const client = v1.NewClient(
  "anything",
  "localhost:50051",
  v1.ClientSecurity.INSECURE_LOCALHOST_ALLOWED
);

async function writeSchema(schemaText: string): Promise<void> {
  await client.promises.writeSchema(
    v1.WriteSchemaRequest.create({ schema: schemaText })
  );
  console.log("Schema written successfully");
}

async function readSchema(): Promise<string> {
  const response = await client.promises.readSchema(
    v1.ReadSchemaRequest.create({})
  );
  return response.schemaText;
}

Scenario - Using the deadline interceptor explicitly

Pass deadlineInterceptor into a call that bypasses the default client setup, or compose it with custom interceptors.

import { v1, deadlineInterceptor } from "./authzed/index.js";
import type { CallOptions } from "@grpc/grpc-js";

const client = v1.NewClient(process.env.AUTHZED_TOKEN!);

const callOptions: CallOptions = {
  interceptors: [deadlineInterceptor],
};

const response = await client.promises.checkPermission(
  v1.CheckPermissionRequest.create({
    resource: v1.ObjectReference.create({ objectType: "doc", objectId: "42" }),
    permission: "view",
    subject: v1.SubjectReference.create({
      object: v1.ObjectReference.create({ objectType: "user", objectId: "u1" }),
    }),
  }),
  callOptions
);

File walkthrough

• index.ts - Barrel export; the single import point for consumers. Exports the v1 namespace, protobuf namespace, and deadlineInterceptor.
• v1.ts - Implements NewClient, NewClientWithCustomCert, all client type aliases (ZedClientInterface, ZedPromiseClientInterface), and re-exports all v1 protobuf message constructors and enums.
• util.ts - Houses ClientSecurity enum, deadlineInterceptor gRPC interceptor, promisifyStream, credential composition logic, and PreconnectServices helpers.
• types.ts - Pure TypeScript utility types used internally and by consumers who need to type their own wrappers: OmitBaseMethods, PromisifiedClient, StreamCall, UnaryCall, WritableStreamCall.
• protobuf.ts - Re-exports protobuf well-known types (Struct, Duration, Timestamp, FileDescriptorProto) for consumers who need to work with raw protobuf values.
• authzedapi/ - Generated code only; contains message types and gRPC client stubs for v1 (permissions, schema, watch, experimental) and materialize v0 (WatchPermissions, WatchPermissionSets). Do not edit manually.
• __utils__/ - Internal helpers (helpers.ts) used in tests. Not part of the public surface.

Common pitfalls and fixes

• .js extension import errors in CJS projects: The source uses ESM-style .js imports internally. Fix by setting "module": "Node16" and "moduleResolution": "Node16" in tsconfig.json, or transpile with esbuild.
• INSECURE_LOCALHOST_ALLOWED rejected in production: The insecure credential modes skip TLS entirely. Never set them outside local dev; use SECURE with a real token and endpoint instead.
• Calls hanging with no error: The gRPC channel connected but the server is unresponsive. Ensure deadlineInterceptor is in the interceptor chain, or set deadline explicitly on CallOptions.
• google-protobuf not found at runtime: It is a hard runtime dependency for the generated protobuf code. Run npm install google-protobuf and verify it appears in node_modules.
• Streaming calls not promisified: Only unary calls are auto-promisified on .promises. For streaming methods (e.g. watchRelationships), use the raw callback-based method on the top-level client and handle the ClientReadableStream manually.
• Token passed as empty string causes silent auth failures: SpiceDB in dev mode may accept empty tokens, but Authzed cloud will return UNAUTHENTICATED. Always validate process.env.AUTHZED_TOKEN is set before constructing the client.

Vibe-coding prompt template

I have dropped the authzed-node SDK source into `src/authzed/` in my project.
The USAGE.md file is at `src/authzed/USAGE.md`. The upstream package is
`@authzed/authzed-node@0.19.0`.

Please help me integrate this into my existing TypeScript/Node.js project
step by step:

1. Read USAGE.md and the file excerpts to understand the real exported symbols.
2. Install all required npm dependencies listed in the "Required dependencies" section.
3. Update my tsconfig.json to support the ESM module resolution the source requires.
4. Create a singleton `src/lib/authzed.ts` that initializes the client using
   environment variables AUTHZED_TOKEN and AUTHZED_ENDPOINT, and exports helper
   functions for checkPermission, writeRelationship, and deleteRelationship.
5. Wire the client into my Express request handlers so every protected route
   calls checkPermission before proceeding.
6. Add error handling for PERMISSION_DENIED and UNAUTHENTICATED gRPC status codes.

Only use exports that are visible in USAGE.md. Do not invent method names.

License and credit

The upstream project is licensed under the Apache License 2.0 (as shown in the README badge). Source and full license text: https://github.com/authzed/authzed-node. NPM package: @authzed/authzed-node.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完整安装指南与集成提示词将在购买后解锁。