Skip to content

authentication.mdx

Latest commit

 

History

History
89 lines (68 loc) · 3.05 KB

authentication.mdx

File metadata and controls

89 lines (68 loc) · 3.05 KB
title Authentication
description Create API keys and authenticate requests to SenderKit.
icon key

Every request to the SenderKit API authenticates with an API key passed as a Bearer token:

Authorization: Bearer sk_live_...

Getting a key

Create keys in the dashboard. The plaintext secret is shown once at creation and stored only as a SHA-256 hash afterward — copy it then, because it can't be retrieved later. The SDK and CLI read the key from the SENDERKIT_API_KEY environment variable.

Live and test keys

Keys carry an sk_live_ or sk_test_ prefix that selects the environment:

  • sk_live_ delivers real notifications through your connected providers.
  • sk_test_ never calls providers — use it for local development and CI.

The prefix is only a hint for humans; the secret is the full token. SenderKit derives live-versus-test mode from the prefix server-side, so the same code path behaves correctly just by swapping the key.

Scopes

API keys carry an optional scope set that limits what a credential can do. You pick scopes in the dashboard at creation time; all three are selected by default.

Scope Authorizes
read GET /v1/messages, GET /v1/messages/{id}, GET /v1/context, GET /v1/templates, GET /v1/templates/{slug}, and template render
send POST /v1/send, POST /v1/send-raw, and draft template operations
cancel DELETE /v1/messages/{id}

A key created without selecting any explicit scope is unscoped and has full access — all keys minted before scope enforcement are unscoped by default and continue to work without changes. A scoped key used outside its grant returns 403 with code: "insufficient_scope". The SDK surfaces this as SenderKitPermissionError, distinct from the SenderKitAuthenticationError raised for 401s, so you can handle the two cases separately.

Revocation

To retire a key, revoke it in the dashboard — a revoked or otherwise invalid key returns 401 Unauthorized. There's no in-place rotation: to rotate, create a new key, deploy it, then revoke the old one.

Authenticating a request

```bash curl curl https://api.senderkit.com/v1/send \ -H "Authorization: Bearer $SENDERKIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "template": "welcome", "to": "user@example.com", "vars": { "name": "Ada" } }' ``` 
import { SenderKit } from "@senderkit/sdk";

// Reads the key you pass in from the environment.
const senderkit = new SenderKit({ apiKey: process.env.SENDERKIT_API_KEY! });
import { SenderKit } from "@senderkit/sdk";

const senderkit = new SenderKit({ apiKey: "sk_live_..." });
Treat API keys as secrets. Keep them server-side only — never ship them in client-side bundles or commit them to source control. Store them in your platform's environment variables or a secrets manager.