Skip to main content

Authentication

Every request carries a personal access key: a secret that starts with gak_. A key acts as you: it reads what you can see in the Spendbaker app, and it can't change anything.

Personal access keys only, for now

Today you can only create personal access keys, which act as the person who created them. Organization access keys, which act as the whole organization, are coming. See Organization access keys.

Create a key​

  1. In Spendbaker, open Settings › API & Keys.
  2. Click Create key.
  3. Give it a name that says where it is used, such as "BI dashboard".
  4. Choose when it expires: 30 days, 90 days (the default), 1 year or never.
  5. Copy the key. It is shown only once. If you lose it, revoke it and create a new one.

Your email address must be verified to create a key. You can hold up to 20 live keys.

The same page lists your keys, with when each one was created, when it expires and when it was last used.

Send the key​

Put the key in the Authorization header, after Bearer:

curl https://app.spendbaker.com/sb_back/api/v1/organization \
  -H "Authorization: Bearer gak_…"

This header is the only place the API reads a key. A key in the query string, in a cookie or in another header is ignored, and the request gets 401 missing_key.

Call GET /organization first: it tells you which organization and which user the key acts as.

What a key can read​

A key has your rights, and only yours, at the moment of each request:

  • Budgets: the budgets shared with you, their categories and their expenses. A budget nobody shared with you stays hidden, even if you are an admin of the organization.
  • Vendors: every vendor of your organization.
  • Members: the members of your organization, with their names and role.

Rights are checked on every request. If someone stops sharing a budget with you, your keys stop seeing it at once.

What a key can't do​

  • Change anything. Every key is read-only: the API has no route that creates, edits or deletes.
  • Read what you can't see in the app, such as budgets not shared with you.
  • Read contact details: members' email and phone, and vendors' email, are never returned.
  • Call the app's own routes. A key works on this API, under /sb_back/api/v1. The app's other routes refuse it with a 401.

When a key stops working​

A key stops working, at once:

  • when it expires;
  • when you revoke it, in Settings › API & Keys;
  • when you leave the organization, or are removed from it.

A key that doesn't work gets 401 invalid_key. The API doesn't say why: an expired, revoked or unknown key all look alike. Create a new key.

Organization access keys​

Not available yet: they are coming. An organization access key will act as the organization, not as one person.

Budgets are shared with people, so the routes that read budgets and expenses will refuse organization access keys with 403 personal_key_required. /organization, /users and /vendors will accept them.

Keep your key secret​

Anyone who holds your key reads what you can read.

  • Call the API from a server or a script, never from a web page or a mobile app. The API doesn't allow calls from other websites in a browser (CORS).
  • Keep the key in a secret store or an environment variable, never in source code or a URL.
  • Use one key per tool, so you can revoke one without breaking the others.
  • If a key may have leaked, revoke it right away.