API & SDK

SDK

@signata/sdk is a typed client plus a few drop-in UI pieces. It wraps the same REST API documented in the API reference and returns the same verification contract, so the SDK, the API, and the badge always agree.

Install

shell

npm install @signata/sdk

SignataClient

Construct a client with your API key (and an optional baseUrl). Keep the key server-side; for browser use, mint a scoped public key.

client.ts

import { SignataClient } from "@signata/sdk";

const client = new SignataClient({
  apiKey: process.env.SIGNATA_API_KEY!,
  // baseUrl is optional; defaults to your Signata deployment.
  baseUrl: "https://app.signata.dev",
});

verify(input)

Verifies an asset and resolves to the full VerificationResponse. Branch on result.verdict, and remember no_provenance means “unknown,” never “fake.”

verify.ts

// verify() accepts bytes: Uint8Array | ArrayBuffer | Blob | Buffer.
const result = await client.verify(bytes);

if (result.verdict === "verified") {
  // origin + integrity confirmed, and the signer is trusted.
} else if (result.verdict === "tampered") {
  // a credential exists but the bytes changed after signing.
} else if (result.verdict === "no_provenance") {
  // unknown, not a signal of fakery. Most media is unsigned.
}

// AI disclosure is orthogonal to the verdict.
if (result.ai.generated) {
  showBadge("AI-generated (disclosed)");
}

sign(input, opts)

Signs an asset, records it in the transparency log, and returns the credentialed bytes plus a receipt. If AI was involved, disclose it in opts.ai. Disclosure co-exists with a verified verdict.

sign.ts

const receipt = await client.sign(bytes, {
  title: "Press photo, city hall",
  ai: { generated: false, edited: false },
});

// receipt.credentialed_asset_base64: the signed bytes to store/serve
// receipt.asset.hash                : the content hash to recover by
// receipt.transparency.{ seq, entry_hash, log_root }

ProvenanceBadge (React)

A React component that verifies an asset and renders the honest verdict card for you: the same vocabulary as the rest of the product. Pass the asset URL or bytes; it handles the rest.

PhotoCard.tsx

import { ProvenanceBadge } from "@signata/sdk/react";

export function PhotoCard({ src }: { src: string }) {
  return (
    <figure>
      <img src={src} alt="" />
      {/* Fetches verification for the asset and renders the honest
          verdict card: verified / untrusted / tampered / no_provenance,
          plus any AI disclosure. Never renders "real" or "fake". */}
      <ProvenanceBadge asset={src} />
    </figure>
  );
}

The badge deliberately renders only the verdict, the signer’s trust status, and any AI disclosure. It will never display “authentic” or “real.” Those words aren’t in its vocabulary.

Framework middleware

provenanceGuard wraps a route handler: it verifies an incoming upload, evaluates your workspace policy, and hands you the decision so you can allow, label, queue for review, or block.

route.ts

import { provenanceGuard } from "@signata/sdk/server";

// Verify an upload and apply your workspace policy before accepting it.
export const POST = provenanceGuard(
  { apiKey: process.env.SIGNATA_API_KEY! },
  async (req, { verification }) => {
    // verification is the full VerificationResponse.
    // The policy decision drives what you do next:
    switch (verification.policy?.actions[0]) {
      case "block":   return new Response("Rejected", { status: 422 });
      case "review":  return enqueueForHumanReview(req, verification);
      default:        return accept(req, verification); // allow / label / disclose
    }
  },
);

Embeddable script

For plain HTML pages with no build step, the hosted /signata-badge.js renders a badge from data attributes. Use a public, verify-only key.

index.html

<!-- Drop-in badge for any page. No build step, no framework. -->
<script
  src="https://app.signata.dev/signata-badge.js"
  data-asset="https://cdn.example.com/photo.jpg"
  data-api-key="pk_pub_xxx"
  async
></script>

For programmatic access without the SDK, every call here maps directly to a REST endpoint. See the API reference and the OpenAPI spec.