Authentication

Spatibase has three separate kinds of credentials: a sign-in session for people using the web app, API keys for websites and apps reading a private project’s Content Delivery API, and edit keys for AI assistants. This page explains each one and helps you pick the one you need.

Which credential do I need?

For most websites and maps you need no credential at all, because a project’s Content Delivery API is public by default. Pick from this table for anything else:

How do people sign in to the web app?

People sign in to https://app.spatibase.com with an emailed link; there are no passwords. Enter an email address, click Send me a sign-in link, and open the link from the email. The link works once and expires after 15 minutes. The email also has a 6-digit code to type on the sign-in page instead of using the link, which is how people sign in to an app added to a phone’s Home Screen. A new address creates an account on first use.

• Each person sees only the projects they are a member of. Other people’s projects answer 404, as if they did not exist.
• Members are Owners (everything; whoever creates a project), Editors (content: entries, groups, files, publishing, import and export, the trash, the map style) or Developers (API keys, webhooks and AI assistant connections). An action a role cannot do answers 403 with a plain message. Details are in Members and roles.
• Scripts that call the Content Management API sign in the same way and keep the session cookie. API keys and edit keys do not work on the Content Management API: with only a key it answers 401. See Content Management API.
• A browser page on another website cannot change data with your session: a write that comes with another site’s Origin answers 403. Scripts and servers send no Origin header and are not affected.

Content Delivery API keys

A Content Delivery API key lets a website, app or server read a private project’s published content. Keys are read-only: they cannot change anything.

Public and private projects

Every project’s Content Delivery API is either public or private, chosen by an owner in the project’s API, on Access & keys:

• Public (the default): anyone who has the project’s URLs can read its published entries, with no key. The project id is the only identifier, so treat it as public.
• Private: every Content Delivery API request needs a valid key of that project. Everyone else gets 401.

Drafts are never readable through the Content Delivery API either way. Public projects accept and ignore keys, so you can add a key to your site before making the project private. How editors switch is described in Access and API keys.

How do I send an API key?

Send the key in one of three ways; the first one present counts:

curl -H "Authorization: Bearer $API_KEY" "https://api.spatibase.com/delivery/v1/projects/$PROJECT_ID/entries?limit=1"
curl -H "X-API-Key: $API_KEY" "https://api.spatibase.com/delivery/v1/projects/$PROJECT_ID/types"
curl "https://api.spatibase.com/delivery/v1/projects/$PROJECT_ID/tiles.json?api_key=$API_KEY"

$PROJECT_ID is the UUID in the project’s address in the web app, and $API_KEY is a key created on its API page. Keys for websites and apps start with sb_live_, followed by 32 letters and digits.

Prefer a header. ?api_key= exists for map libraries and GIS tools that load tile URLs without custom headers. URLs end up in server, proxy and browser logs and history, so rotate a key if it leaks. Edit keys (sb_edit_) are refused in ?api_key=; send them in a header.

In the browser, CORS preflight requests need no key, and Authorization and X-API-Key are allowed request headers.

What happens without a valid key?

A private project answers 401 when the key is missing, and 401 with a different code when the key is not valid for that project:

HTTP/1.1 401 Unauthorized
Cache-Control: no-store
WWW-Authenticate: Bearer realm="Spatibase Delivery API"

{"error":{"code":"api_key_required","message":"This project’s Content Delivery API is private. Send an API key: Authorization: Bearer <key>, X-API-Key: <key> or ?api_key=<key>."}}

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Spatibase Delivery API", error="invalid_token"

{"error":{"code":"api_key_invalid","message":"This API key isn’t valid for this project. Check it, or create a new one: keys can be revoked or expire."}}

• api_key_invalid is the same for a mistyped, revoked or expired key and for a key of another project.
• The key check runs first, so a private project answers 401 even for an unknown entry, a bad parameter, or an If-None-Match that would otherwise have been a 304.
• After 60 failed key checks with unknown keys from one IP address within 10 minutes (revoked, expired and other projects’ keys do not count), further requests from that address that send a key to a private project get 429 with code: "rate_limited" and a Retry-After header in seconds, until the window has moved on. Requests without a key, other addresses and public projects are not affected.

How are private responses cached?

Successful responses of a private project carry Cache-Control: private, max-age=60 and Vary: Authorization, X-API-Key: browsers may keep them for 60 seconds, and CDNs and shared proxies must not store them. ETag and 304 work as usual when you send the key with the conditional request.

Switching a project between public and private changes every ETag. Spatibase serves the Content Delivery API through its own CDN: public copies cached before the switch can stay there for up to about five minutes (s-maxage 300 seconds, plus stale-while-revalidate), and browsers may reuse theirs for up to 60 seconds. There is nothing to purge on your side, unless you run a cache of your own in front of the API.

How do keys work with map tiles?

Request TileJSON with ?api_key= and the tiles URL template in the response carries the same key, so MapLibre GL, Mapbox GL and QGIS load tiles without headers:

["https://api.spatibase.com/delivery/v1/projects/41d8624b-d321-4584-b3e6-70c14903e419/tiles/{z}/{x}/{y}.pbf?api_key=sb_live_..."]

With a header key, the template carries no key, so add the header to tile requests yourself (in MapLibre GL, with transformRequest). Paging links keep the request’s query string, so they carry api_key too. Examples are in GeoJSON and vector tiles.

Are asset files protected in a private project?

No. Asset URLs (/assets/<id>/<filename>) of a private project work without a key, because an <img> tag cannot send one. Their URLs are long and random, but anyone who has a URL can open the file. See Assets and images.

How are keys created and managed?

Owners and Developers create keys in the project’s API, on Access & keys, with Create key and For a website or app. Editors cannot see or manage keys.

• A key is shown once, when it is created. Spatibase stores only a hash, so a lost key cannot be shown again; create a new one.
• Keys can be renamed, given an expiry date, replaced (Replace makes a new key with the same name and switches the old one off at once) and revoked (Revoke switches a key off for good).
• A project can have up to 50 active keys.
• A key in a web page’s code is visible to every visitor. Use one key per website or app, so you can replace one without breaking the others.

Step-by-step instructions are in Access and API keys.

Edit keys for AI assistants

An edit key connects an AI assistant to one project through the Spatibase MCP server. It starts with sb_edit_ and is created on the API page with Create key and For an AI assistant. Only project Owners can create edit keys.

• An edit key reads published content like a read key, and also reads and changes drafts.
• Publishing (marking ready, publishing the project, going back to a version, group membership) and deleting are two separate switches on the key, Allow publishing and Allow deleting, both off by default. Only Owners can switch them on; Owners and Developers can switch them off.
• An edit key never manages API keys, members or the webhook, never switches a project between public and private, never changes the content model (types, fields, map feature types, groups themselves) or the project’s settings, never duplicates or deletes a project and never empties the trash. Every change it makes appears in the project’s activity as made by the AI assistant, with the key’s name.
• An edit key also works as a Content Delivery API key, in a header only. It does not work on the Content Management API.
• Treat an edit key like a password, because it can change your drafts. Revoke it when the assistant no longer needs access.

Members can also connect an assistant by signing it in with their own account instead (OAuth); the assistant then gets at most the scope of their role (a Developer’s assistant can only read). Setup is in Connect an assistant, and what an assistant may do in What assistants can do.

Related

• Access and API keys
• Content Delivery API reference
• MCP server
• Members and roles