Authentication

Learn how to authenticate API requests using API keys with scope-based access control

Authentication

The Seal API uses API keys for authentication. All API requests must include a valid API key in the Authorization header.

Creating an API Key

API keys are created in the Seal app at Settings → Developer → API keys:

Sign in to the Seal app at app.seal.nyc
Go to Settings → Developer → API keys
Click Create API Key
Select the required scopes for your integration
Copy the generated API key — it is shown only once at creation (format: ak_xxx)

API Scopes

Seal uses scope-based access control to limit what each API key can do. Select only the scopes your integration needs:

Scope	Description	Endpoints
`seal:documents:read`	Read document metadata and content	GET /documents, GET /documents/, GET /documents//download
`seal:documents:write`	Create, update, delete documents	POST /documents, PATCH /documents/, DELETE /documents/, POST /documents//send, POST /documents//void
`seal:templates:read`	Read template metadata and fields	GET /templates, GET /templates/, GET /templates//fields
`seal:templates:write`	Create, update, delete templates	POST /templates, PATCH /templates/, DELETE /templates/
`seal:recipients:read`	Read recipient information	GET /documents//recipients, GET /recipients/
`seal:recipients:write`	Manage document recipients	POST /documents//recipients, PATCH /recipients/, DELETE /recipients/, POST /recipients//remind
`seal:signatures:read`	Read signature data and audit trails	GET /signatures, GET /signatures/, GET /signatures//verify, GET /signatures//audit
`seal:webhooks:manage`	Create, update, delete webhooks	Webhook management endpoints
`seal:members:read`	Read organization members	Member endpoints
`seal:settings:read`	Read organization settings	Settings endpoints
`seal:settings:write`	Update organization settings	Settings endpoints
`seal:audit:read`	Read audit logs	Audit log endpoints
`seal:contacts:read`	Read contacts	Contact endpoints
`seal:contacts:write`	Create, update, delete contacts	Contact endpoints

Making Authenticated Requests

Include your API key in the Authorization header using the Bearer scheme:

TypeScript Example

const response = await fetch("https://api.seal.nyc/api/v1/documents", {
  method: "GET",
  headers: {
    Authorization: "Bearer ak_your_api_key_here",
    "Content-Type": "application/json",
  },
});

if (!response.ok) {
  const error = await response.json();
  console.error("API Error:", error);
  throw new Error(error.detail);
}

const documents = await response.json();
console.log("Documents:", documents);

cURL Example

curl -X GET https://api.seal.nyc/api/v1/documents \
  -H "Authorization: Bearer ak_your_api_key_here" \
  -H "Content-Type: application/json"

Authentication Errors

Status Code	Error	Description
401	`MISSING_AUTH_HEADER`	No Authorization header provided
401	`INVALID_AUTH_FORMAT`	Authorization header format is incorrect
401	`INVALID_API_KEY`	API key is invalid or expired
403	`INSUFFICIENT_SCOPE`	API key lacks required scope for this endpoint
403	`ORGANIZATION_ACCESS_DENIED`	User has no active organization

Best Practices

Use HTTPS: Always make requests over HTTPS to protect your API key in transit
Rotate Keys: Regularly rotate API keys, especially if they may have been compromised
Environment Variables: Store API keys in environment variables, never hardcode them
Monitor and Revoke: Monitor and revoke keys from Settings → Developer → API keys in the Seal app
Separate Keys: Use different API keys for development, staging, and production environments

Next Steps

Now that you understand authentication, check out the Quick Start guide to send your first document for signing.