API keys
An API key lets a map client such as QGIS or ArcGIS Pro load the imagery in chosen projects as map tiles, without anyone signing in. Keys are under Settings > API Keys.
What a key can do
- It works only with the Albatross Tiles API. It cannot sign in to the web app or call anything else.
- It reads only the projects you choose, as a project Viewer. Its access, Map tiles (WMTS) (
tiles:read), cannot be changed. - Every key expires.
- Every tile it loads counts towards your workspace's tile usage. See Tiles API metering.
Who can do this
Only a workspace Admin can see, create, edit, roll or revoke keys and view their usage.
A project Manager can also take their project away from a key: in the project's member list the key's role shows as "API key: Map tiles", and its row menu has Remove API Key from Project. Only an Admin can add it back.
Before you start: map tiles must be enabled
Terrabit enables Map tiles (WMTS) for your workspace, optionally with a start date, an end date and a monthly tile quota. To enable it, contact your account manager or contact support.
| Map tiles state | Create or roll a key | Keys load tiles |
|---|---|---|
| Not enabled | No | No |
| Starts on a future date | Yes | Not until the start date |
| Active | Yes | Yes |
| Ended | No | No |
Dates are in UTC: access stops at 00:00 UTC on the end date.
Create an API key
In Settings > API Keys, select Create API Key, then choose a Name, how long it Expires after and at least one project.
The name must be unique among the workspace's live keys; a revoked key's name can be reused. For lifetimes and other limits, see Limits and time zones.
Copy the key now
The API Key Created dialog is the only time the key (starting alb_) is shown. Copy it before you select Done. If you lose it, roll the key.
Connect a map client
The create and roll dialogs, and the Connect section on a key's page, show your workspace's WMTS capabilities URL. The URL carries no key: the key you authenticate with decides which layers the client sees.
- QGIS: add a WMS/WMTS connection with the URL. Under Authentication, add an API Header
Authorizationwith the valueBearer <key>, or use Basic with any username and the key as the password. - ArcGIS Pro: Insert > Connections > Server > New WMTS Server, paste the URL and, under Server Authentication, enter any username and the key as the password.
See Add your data to a GIS for the full guide. Connect to GIS in the Data Catalog also copies WMTS URLs for the catalogue, an area or a capture while map tiles are active.
Key statuses
| Status | Meaning |
|---|---|
| Active | The key works. |
| Expiring | The key expires within 14 days. |
| Expired | Map clients can no longer load tiles with it. You can still roll it. |
| Revoked | The key can never work again. Hidden from the list. |
View a key
Select a key's name to see its details, projects, this month's usage (UTC) and connection instructions. The key itself is never shown again. "Last active" is a UTC day, not an exact time.
Rename a key or change its projects
Select Edit API key. Changes reach map clients within a minute. To change the expiry, roll the key.
Roll a key
Rolling issues a new key with a new expiry, keeping the name, projects and usage history. Select Roll API key, choose when the new key expires, then copy it and update every map client.
The old key stops working within a minute, with no overlap. To switch clients without downtime, create a second key, move clients to it, then revoke the first.
You can roll an expired key, but not a revoked one, or any key while map tiles are ended or not enabled.
Revoke a key
Select Revoke API key. Within a minute every map client using it loses access. This cannot be undone: create a new key (it may reuse the name) to restore access. The key's usage stays in Tile Usage.
Expiry alerts
Workspace Admins get an API Key {name} Expiring Soon notification 14 days before a key expires, once per expiry date, so rolling sets up a new alert. None is sent while map tiles are ended or not enabled. See Notifications.
Errors a map client may report
See the status codes in Troubleshooting. A 401 includes the old key after a roll.
Changes to a key or to map tiles take up to a minute to reach map clients, and a client may keep showing tiles it cached for up to an hour.