SDK Reference

Node.js / TypeScript SDK

@secr/sdk provides programmatic access to the secr API for Node.js applications. It powers the Vercel and Netlify integrations and can be used to build custom integrations.

Installation

npm install @secr/sdk

Requires Node.js 20+ (uses global fetch).

Quick Start

pull-secrets.ts

import { SecrClient } from "@secr/sdk";

const client = new SecrClient({
  token: "secr_tok_...",
  apiUrl: "https://api.secr.dev", // optional, this is the default
});

// Pull all secrets for an environment
const { secrets } = await client.pullSecrets(
  "my-org", "my-project", "production"
);

for (const s of secrets) {
  console.log(`${s.key}=${s.value}`);
}

Constructor

new SecrClient(options: SecrClientOptions)

Option	Type	Required	Description
token	string	Yes	secr CLI token (secr_tok_...)
apiUrl	string	https://api.secr.dev	API base URL (trailing slash stripped)
timeout	number	30000	Request timeout in milliseconds

Methods

pullSecrets(org, project, env, options?)

Pull all decrypted secrets for an environment.

Example

const { secrets, pagination } = await client.pullSecrets(
  "my-org", "my-project", "development",
  { limit: 50, offset: 0, search: "DB_" }
);

Returns { secrets: ApiSecret[], pagination?: PaginationInfo }

listKeys(org, project, env, options?)

List secret keys without values.

Example

const { keys } = await client.listKeys(
  "my-org", "my-project", "production"
);

Returns { keys: ApiSecretMeta[], pagination?: PaginationInfo }

setSecret(org, project, env, key, value)

Create or update a single secret.

Example

const { key, version } = await client.setSecret(
  "my-org", "my-project", "development",
  "API_KEY", "sk_live_..."
);

bulkSetSecrets(org, project, env, secrets)

Create or update multiple secrets at once.

Example

const result = await client.bulkSetSecrets(
  "my-org", "my-project", "development",
  [
    { key: "DB_URL", value: "postgres://..." },
    { key: "REDIS_URL", value: "redis://..." },
  ]
);
// result: { created: 1, updated: 1, total: 2 }

deleteSecret(org, project, env, key)

Soft-delete a secret.

Example

await client.deleteSecret(
  "my-org", "my-project", "development", "OLD_KEY"
);

Promote Secrets

promoteSecrets(org, project, options)

Copy secrets from one environment to another.

Example

const result = await client.promoteSecrets(
  "my-org", "my-project",
  {
    fromEnv: "staging",
    toEnv: "production",
    overwrite: true,
    keys: ["DB_URL", "API_KEY"], // optional, promotes all if omitted
  }
);
// result: { promoted: 2, created: 1, updated: 1, skipped: 0 }

Templates

listTemplates(org, project)

List required key templates for a project.

Example

const { templates } = await client.listTemplates(
  "my-org", "my-project"
);

validateTemplate(org, project, env)

Check if an environment has all required keys.

Example

const { valid, missing, extra } = await client.validateTemplate(
  "my-org", "my-project", "production"
);

if (!valid) {
  console.error("Missing keys:", missing);
}

Error Handling

All errors are thrown as SecrApiError:

error-handling.ts

import { SecrClient, SecrApiError } from "@secr/sdk";

try {
  await client.pullSecrets("my-org", "bad-project", "dev");
} catch (err) {
  if (err instanceof SecrApiError) {
    console.error(err.message);     // "Project not found"
    console.error(err.statusCode);  // 404
    console.error(err.code);        // "not_found"
  }
}

Code	Meaning
invalid_config	Constructor options invalid (e.g. missing token)
timeout	Request timed out
connection_error	Cannot reach the API server
network_error	Other network failure
not_found	Resource doesn't exist (404)
api_error	Generic API error (check statusCode)

Pagination

The pullSecrets and listKeys methods accept optional pagination parameters:

Option	Type	Required	Description
limit	number	No	Max results per page (1-500)
offset	number	No	Number of results to skip
search	string	No	Filter keys by prefix

When limit is provided, the response includes a pagination object with { limit, offset, total }. When omitted, all results are returned.

TypeScript

All types are exported:

types.ts

import type {
  SecrClientOptions,
  PullSecretsResult,
  ListKeysResult,
  ApiSecret,
  ApiSecretMeta,
  PaginationInfo,
  SecrApiError,
} from "@secr/sdk";

API response types (ApiSecret, ApiSecretMeta, etc.) are re-exported from @secr/shared.

Start building with the SDK

npm install @secr/sdk

Create Free Account Back to Docs