One authorization call on your server.

Private Beta package status

@gatekit/sdk v0.1.0 is implemented and build-ready inside the GateKit monorepo. Public npm publication is a separate deliberate Private Beta release step.

Install

After the Private Beta npm release:

pnpm add @gatekit/sdk

Verify a wallet

import { createGateKitClient } from "@gatekit/sdk";

const gatekit = createGateKitClient({
  apiKey: process.env.GATEKIT_API_KEY!,
});

const result = await gatekit.verify({
  policyId: process.env.GATEKIT_POLICY_ID!,
  wallet: "0x0000000000000000000000000000000000000001",
});

if (result.status === "allowed") {
  // Grant result.entitlements
} else if (result.status === "denied") {
  // Conclusive policy denial
} else {
  // Verification unavailable: fail closed
}

The SDK returns the same deterministic allowed, denied, and error decision model as the REST API.

Next.js server integration

Create one server-only client:

// lib/gatekit.ts
import "server-only";
import { createGateKitClient } from "@gatekit/sdk";

export const gatekit = createGateKitClient({
  apiKey: process.env.GATEKIT_API_KEY!,
});

Then call it from a trusted Route Handler or other server boundary:

// app/api/access/route.ts
import { NextResponse } from "next/server";
import { gatekit } from "@/lib/gatekit";

export async function POST(request: Request) {
  const { wallet } = await request.json();

  const result = await gatekit.verify({
    policyId: process.env.GATEKIT_POLICY_ID!,
    wallet,
  });

  if (result.status === "error") {
    return NextResponse.json(
      { error: "authorization_unavailable" },
      { status: 503 },
    );
  }

  if (!result.allowed) {
    return NextResponse.json({ error: "forbidden" }, { status: 403 });
  }

  return NextResponse.json({
    allowed: true,
    entitlements: result.entitlements,
  });
}

Keep credentials in server environment variables:

GATEKIT_API_KEY=gk_test_...
GATEKIT_POLICY_ID=pol_...

Treat denial and infrastructure failure differently

allowed means the policy conclusively passed. denied means it conclusively failed. error means GateKit could not produce a trustworthy authorization decision.

Applications should fail closed when verification returns status: "error", but should not mislabel that infrastructure condition as a normal policy denial.

Authentication, invalid requests, and rate limits

import { GateKitApiError } from "@gatekit/sdk";

try {
  const result = await gatekit.verify({ policyId, wallet });
} catch (error) {
  if (error instanceof GateKitApiError) {
    if (error.status === 429) {
      console.log("Retry after", error.retryAfterSeconds, "seconds");
    }

    console.error(error.code, error.status);
  }
}

Auth failures, invalid requests, missing policies, and quota responses throw GateKitApiError. HTTP 429 exposes the server retry interval as retryAfterSeconds.

Keep GateKit secrets server-side

Never put gk_test_... or gk_live_... keys in browser JavaScript, localStorage, an extension bundle, or a NEXT_PUBLIC_* variable.

A browser/React SDK will only ship after GateKit has short-lived, scoped client authorization with expiry, audience/origin binding, and replay controls.