Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.scripe.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Scripe API — Authentication (v1)

Status: Public preview. The Scripe API is rolling out to Advanced and Business plans. Behaviour and scopes documented here are stable for v1; new resources will land in additive minor releases (v1.1, v1.2…). Breaking changes will only ship in v2 with a deprecation window of at least 90 days.
This document covers everything you need to authenticate against the Scripe public API: the key concept, the wire format, how to mint and rotate keys from the dashboard, and how to recover from a compromise. If you’re integrating an MCP server, the same key works — see mcp.md for transport-specific notes (coming with Phase 4).

​
TL;DR

GET /v1/notes
Host: api.scripe.io
Authorization: Bearer scripe_sk_live_8f3a…d401
  • One key per integration. Treat it like a password.
  • Live mode and test mode are both real keys against the real API; the difference is that test keys are flagged in audit logs and (from Phase 4 onwards) won’t trigger external side-effects (e.g. LinkedIn publishing).
  • Keys are workspace-scoped and only act inside the workspace they were minted in. There is no cross-workspace token.
  • Revocation is immediate (≤ 5 seconds in the worst case).

​
1. Concepts

​
1.1 Workspace-scoped keys

Every API key belongs to exactly one Scripe workspace and authorises actions inside that workspace only. There is no organisation-wide super-key. If you have multiple workspaces (e.g. an Agency cohort), mint one key per workspace in the workspace’s own Developer settings. This is the same boundary the dashboard uses — a request authenticated by an API key sees the same data the bearer of that key would see if they signed in interactively as the workspace.

​
1.2 Scopes

Scopes are least-privilege by default. A key has zero permissions until you explicitly tick the resource scopes it needs. v1 ships with these scopes; the catalog grows with each phase:
ScopeWhat it grantsAvailable in
notes:readRead notes the workspace ownsv1.0
notes:writeCreate/update/delete notesv1.0
posts:readRead post drafts and scheduled postsv1.0
posts:writeCreate post drafts, trigger post creationv1.1
Granting a write scope does not automatically include the matching read scope — most write endpoints don’t need to read anything back. Tick both if your integration needs both.

​
1.3 Live vs test keys

The type field on every key is either live or test. Both keys hit the same /v1 endpoints, but:
  • Live keys count against your workspace’s request-rate limits and may trigger external side effects (publishing to LinkedIn, sending emails to end-users, etc.).
  • Test keys are tagged in audit logs and will not trigger external side effects from Phase 4 onwards. Use them for CI, staging, or local dev.
Both flavours ship with the same scopes. There is no “sandbox” data set — your test key reads and writes the same workspace data your live key does. If you want isolation, mint a key in a dedicated test workspace.

​
1.4 Expiry and rotation

A key can have an optional expiresAt date. After that day at 00:00 UTC the key fails open requests with 401 Unauthorized — the row stays in the database for audit, it just stops authenticating. Best practice: rotate any long-lived key every 90 days. The dashboard’s New API key wizard lets you set an expiry up front, which is the cheapest way to enforce rotation without writing custom code.

​
2. Wire format

​
2.1 Header

Authorization: Bearer <key>
We accept the Bearer scheme only. We do not accept the API key in a query parameter, a cookie, or a custom header — those routes leak credentials into logs, browser history, and proxies.

​
2.2 Key format

scripe_sk_<live|test>_<24+ url-safe random chars>
  • scripe_ — vendor prefix. Lets secret-scanning tools (GitHub, GitGuardian) recognise leaked keys.
  • sk_ — “secret key”. Reserved for future flavours like pk_ (publishable, read-only, browser-safe).
  • live_ / test_ — mode discriminator. Visible to humans; no security meaning.
  • The trailing 24+ characters are the actual entropy. We store an HMAC-SHA-256 of the full key, never the plaintext.
The full secret is shown to you exactly once, immediately after creation. After that, only the prefix and last 4 characters are visible: 
scripe_sk_live_…d401

​
2.3 Authentication response codes

CodeMeaning
401No key, malformed key, unknown key, revoked key, or expired key
403Valid key, but missing the required scope for the endpoint
429Valid key, but you’ve exceeded the rate limit for this workspace
5xxScripe-side problem. Retry with backoff; we’ll surface them in the
status page
A 401 always means “fix your authentication”. A 403 always means “ask the dashboard for more scopes”.

​
3. Minting a key from the dashboard

You need to be an organisation admin in Scripe and on a plan that includes API access (Advanced or Business at the time of writing).
  1. Open the Scripe dashboard and switch to the workspace you want the key to act in. The key is scoped to this workspace; it cannot read or write other workspaces in the same organisation.
  2. Go to Settings → Developer → API keys.
  3. Click New API key.
  4. Step through the wizard:
    1. Name + mode — give the key a human label (e.g. “Zapier production”) and choose live or test. The label is visible to all org admins; it’s not a secret.
    2. Scopes — tick only the scopes the integration actually needs. You can change the scope set later in Edit.
    3. Advanced — optional expiry date. Leave blank for no expiry.
    4. Reveal — copy the full secret to your password manager or secret store. Tick “I’ve saved this key in a safe place” to close the modal. The dashboard never shows the secret again.
  5. All organisation admins receive a New API key created email immediately after step 4. This is a security signal — if you didn’t expect a co-admin to mint a key, click through and revoke it.

​
3.1 Verifying the key

Once you have the secret, the cheapest sanity check is an authenticated read of your own workspace: 
curl -i https://api.scripe.io/v1/me \
  -H "Authorization: Bearer scripe_sk_live_…"
A 200 OK with your workspace’s id confirms the key works. A 401 means the key was mistyped or revoked; a 403 means the key is fine but lacks the required scope (in this case, none — /v1/me is unauthenticated for scopes).

​
4. Editing scopes and expiry

From Settings → Developer → API keys → Edit you can change:
  • The display name.
  • The scopes the key carries. Both adding and removing scopes takes effect within 5 seconds — we bust the auth cache immediately on save.
  • The expiry date. Removing an expiry takes effect within 5 seconds.
You cannot edit the secret itself. To rotate the secret, mint a new key, deploy it to the integration, then revoke the old one (see §6). Every edit is recorded in the audit log under the actor who saved the change.

​
5. Revoking a key

From Settings → Developer → API keys → Revoke:
  1. The dashboard shows the last 7 days of usage so you can confirm the key you’re revoking is the right one.
  2. Type the key’s name to enable the Revoke button. This guard is here to make accidental revocation hard — there is no undo.
  3. Optional: leave a reason. The reason is stored on the key row and surfaced in the email that goes to all org admins.
Revocation is immediate at the API edge: we bust the Redis auth cache before returning. The hard worst case is 5 seconds (Redis cache TTL), but in practice the cache flush is synchronous and the next request after the mutation 401s.

​
6. Rotation playbook

When you need to rotate a key (suspected compromise, scheduled rotation, employee departure, etc.):
  1. Mint a new key with the same scopes and the same mode.
  2. Deploy it to the integration. Most integrations support a rollover window — set the new key as primary and keep the old one in a fallback slot.
  3. Verify with traffic — watch the new key’s “Last used” timestamp on the dashboard tick over.
  4. Revoke the old key. Any in-flight requests using it will start failing with 401 within seconds.
  5. (If rotating because of a leak) review the audit log for the old key’s keyId to confirm no unexpected actions happened during the exposure window.
For long-lived keys, schedule step 1 for every 90 days — the cheapest defence against silent leaks is a key that simply expires.

​
7. Compromise / incident response

If you suspect a key has leaked:
  1. Revoke immediately. A 5-second propagation delay is the worst case.
  2. Mint a replacement in the same wizard if the integration still needs to run.
  3. Audit. Pull the request log filtered by keyId from Settings → Developer → API keys → [key] → Activity (Phase 6 ships the dedicated audit page; for now use the revoke modal’s chart and the Sentry breadcrumb stream).
  4. Notify. All org admins automatically get the revocation email; for security incidents, copy [email protected].
For more detail (cache invalidation internals, hash chain anchoring, and the ops side of “the key cache is unavailable”), see the operational runbook at packages/api-public/docs/runbook.md.

​
8. FAQ

Can I share a key across workspaces? No. Mint one key per workspace. Can I scope a key to one project inside a workspace? Not in v1. The roadmap has per-project scoping behind the api_v1_project_scoping flag; it’ll ship without breaking existing keys. Can I IP-allowlist a key? Not in v1. Per-key IP allowlists land with Phase 6. What happens to keys when a workspace downgrades to a plan without API access? We invalidate every live key in the workspace’s organisation synchronously when the Stripe webhook fires. Subsequent requests 401. The key rows are kept (not deleted) so they can be re-enabled if the workspace upgrades again — but the secrets are still HMAC-only, so the customer would need to mint new keys to actually use them. Can I see who minted or revoked a key? Yes. Every key row carries createdByUserId / revokedByUserId, which the dashboard resolves to a name, and every email to org admins names the actor. What’s the rate limit? Workspace-level. Live keys count, test keys count, the dashboard does not. Limits are documented in rate-limits.md (lands with Phase 2).