Browse documentation

Type to search the documentation. Press Esc to close.

How do I authenticate with the Scribble API?

For developers

Send an API key as Authorization: Bearer sk_live_…. Create one under Integrations in your Scribble account, ticking only the scopes it needs. The key is shown exactly once: Scribble stores a hash, never the key, so a lost key can only be replaced.

On this page

#The base URL

Text
https://scribblecards.com/api/v1

There is no separate sandbox host and no test key prefix. A card created through this API is a real card and spends a real credit, so develop against an account you have deliberately topped up with a small balance.

#Creating a key

  1. Open Integrations

    In your Scribble account, go to Integrations → New key.

  2. Name it after what it is for

    Production CRM, Nightly contact sync. When a key needs revoking at 2am, the name is what tells you what will break.

  3. Tick only the scopes it needs

    A sync job has no business being able to spend credits. See the scope table below.

  4. Copy the key immediately

    It is shown once. Scribble stores a SHA-256 hash and the visible prefix; the key itself is never stored and cannot be shown again.

    You’ll know it worked when The key looks like sk_live_U9BXdSSU_… and the Integrations screen lists it by its prefix.

#Sending the key

An authenticated request
curl https://scribblecards.com/api/v1/cards \
  -H "Authorization: Bearer sk_live_U9BXdSSU_your_key_here"

The Bearer prefix is required. Nothing else authenticates: there is no query-parameter key, no basic auth and no cookie.

#Scopes

Scopes and what each one permits
ScopePermitsUsed by
cards:sendCreate and send a card. This is the scope that spends credits.POST /cards
cards:readLook up a card's status, recipient and arrival window.GET /cards, GET /cards/{code}
contacts:readList and fetch contacts.GET /contacts
contacts:writeCreate and update contacts. Cannot delete.POST /contacts
403 when a key lacks the scope
{
  "error": {
    "code": "missing_scope",
    "message": "This key does not have the `cards:send` scope. Its scopes are: cards:read.",
    "docs": "https://scribblecards.com/app/integrations"
  }
}

#Authentication errors

Every authentication failure
StatusCodeCause
401missing_keyNo Authorization header, or it is not a bearer token.
401malformed_keyThe token does not start with sk_live_ or has too few segments.
401invalid_keyThe prefix is unknown, or the key does not match the stored hash.
401revoked_keyThe key was revoked. Create a new one and update your integration.
403missing_scopeThe key is valid but lacks the scope this endpoint needs.
429rate_limitedSee rate limits.

#Revoking a key

Revoke from the Integrations screen. It takes effect on the next request. Every key shows its last used timestamp and the IP of the last call, which is how you notice a key that is still in play after you thought it was retired.

#Discovering the API without a key

GET /api/v1 needs no key and describes the whole surface: endpoints, scopes, the webhook signature scheme and the error shape. It is there so somebody who has found the base URL learns what it does without reading anything else.

Discovery
curl https://scribblecards.com/api/v1

Last checked against the product on . Something wrong or missing? Tell us.