Access and API keys
This page is for project owners and developers who share a project’s published content with websites, apps and maps. It covers where the content is available, the choice between a public and a private project, and how to manage API keys in the web app. The technical details of sending a key are in Authentication.
Where is my content available?
Every project has its own address on the Content Delivery API, a read-only API that serves only published entries. To find it:
- Open the project and select API in the side panel.
- In Overview, find API address of this project and select Copy API address. The same address, with a copy button, sits at the bottom of the panel on the left of every API page.
- Give this address to your developer.
From that address the Content Delivery API serves your published content in three forms:
- JSON: entries, types, groups and single entries, 50 entries per page by default and up to 500.
- GeoJSON: the same entries as a map-ready FeatureCollection, 1,000 per request by default.
- Map tiles: vector tiles for map libraries, described by a TileJSON address.
The Endpoints page of API lists every address with a copy button (rows show the part after the API address; the button copies the whole address), including, under For developer tools, the two OpenAPI files developers import into their tools: the Typed OpenAPI file with your own types and fields (a private project needs a key for it, like every other address) and the OpenAPI file (any project) (no key, even on a private project), and Try it lets you run a request and see the answer. See the Content Delivery API reference for every endpoint and parameter.
Should my project be public or private?
The Access & keys page of API decides who can read the published content. Under Who can read it you pick one of two cards, Public or Private, and the text below the cards describes the chosen one.
| Choice | Who can read the published content | When to use it |
|---|---|---|
| Public (the default) | Anyone who has the links. No key is needed. | Public websites and maps. |
| Private | Only websites, apps and scripts that send one of your API keys. Everyone else gets an error. | Content behind your own backend, partner integrations, paid data. |
Drafts are never shared in either case.
Only owners can switch between public and private; for everyone else the cards are switched off, with a note saying so. To make a project private:
- Create an API key for each website and app that reads the project, and add it to them (see How do I create a key?).
- Under Who can read it, select Private and confirm with Make private.
To go back, select Public and confirm with Make public. Your keys are kept, so they work again if you make the project private again.
Important: Switching to private stops every website and app that reads the project without a key, immediately. Copies already cached by Spatibase’s CDN can still be served for up to about five minutes. If you run a cache of your own in front of the API, purge it for this project.
Images and files keep working by their own address on a private project. Their addresses are long and unguessable, but anyone who has one can open it: Spatibase does not sign file URLs.
What is an API key?
An API key is a secret code that lets a website, app or AI assistant use one project. There are two kinds:
| Kind | Starts with | What it allows |
|---|---|---|
| For a website or app (read key) | sb_live_ |
Read the published content of a private project. |
| For an AI assistant (edit key) | sb_edit_ |
Read the project and edit its drafts through the MCP server. Publishing (marking ready, publishing the project, going back) and deleting are separate switches, off by default. An edit key also works as a read key. |
While a project is public, read keys are ignored, but they start working the moment you make it private. Keys only work with the project they were created in.
Who can manage keys?
Owners and developers can see and manage API keys on Access & keys, under API keys. Editors cannot see them.
| Action | Owner | Developer | Editor |
|---|---|---|---|
| Create keys for websites and apps | Yes | Yes | No |
| Create keys for AI assistants | Yes | No | No |
| Rename and revoke any key | Yes | Yes | No |
| Replace a website or app key | Yes | Yes | No |
| Replace an AI assistant key | Yes | No | No |
| Switch Allow publishing or Allow deleting on | Yes | No | No |
| Switch Allow publishing or Allow deleting off | Yes | Yes | No |
Editors and developers who want to use an AI assistant sign it in with their own account instead of a key. See Connect an AI assistant.
How do I create a key?
- Open API and go to Access & keys.
- Under API keys, select Create key (Create your first key while the list is empty).
- Under What is the key for?, choose For a website or app or For an AI assistant (owners only).
- Enter a Name, such as “Company website” or “iOS app”.
- For an AI assistant key, leave Allow publishing and Allow deleting off unless the assistant really needs them. Turning either on asks you to confirm.
- Optionally choose when the key Expires: Never, In 30 days, In 90 days, In 1 year or On a date I pick….
- Select Create key.
Make one key per website, app or assistant. Then you can turn one off without breaking the others. A project can have up to 50 active keys.
Copy the key now
The new key is shown once, in the Copy your key now dialog. Spatibase stores only a fingerprint of it and keeps no copy it could show you again.
- Select the copy button next to the key and store the key somewhere safe, such as a password manager or your app’s secret settings.
- Tick I have copied this key and stored it somewhere safe.
- Select Done.
If you lose a key, create a new one (or replace the old one) and revoke the lost one.
Important: A key placed in a web page’s code is visible to every visitor of that page. Use a separate key for each site, and replace it if it leaks. Keep AI assistant keys out of shared documents and web pages: they can change your drafts.
How do I replace or revoke a key?
The key list shows each key’s name, the first characters of the key, What it can do, Status (with the date an active key expires), when it was created and by whom, and when it was Last used.
- Replace creates a new key with the same name and turns the old one off at once. After you confirm with Replace key (you can set an Expires date for the new key there), the new key appears in a dialog to copy, like any new key. Use it to rotate a key, or when one leaked, and update your site or app with the new key straight away.
- Revoke turns a key off for good. Anything still using it gets an “API key not valid” error. A revoked key cannot be turned back on.
- Rename with the pencil next to a key’s name. The key itself does not change.
Revoked and expired keys stay in the list under Show revoked and expired, so you can see what happened. A revoked key can no longer be renamed.
How do I change what an AI assistant key can do?
For an AI assistant key, select Change under its What it can do to open What “key name” can do, make your change and select Save.
- Switch Allow publishing on to let the assistant mark drafts ready, publish the project, go back to an earlier version and manage group membership.
- Switch Allow deleting on to let it delete entries and files into the trash and restore them.
Turning a switch on asks you to confirm and is for owners only. Turning a switch off takes effect immediately, and developers can do it too. Every change is recorded in Activity.
Try the API pages with a key
On a private project, the side panel of API shows Key for trying things here at the bottom (on a narrow window, at the top of the page). Paste one of your keys there to make Try it, the groups list and the downloads work on every API page. The key stays in that browser tab only: it is never saved and is gone when you reload.
Related
Updated