Documentation menu
Docs / Developers / Authentication

Authentication

An integration has its own role and API keys. Requests must pass both the role’s permissions and the key’s scope. Keep keys in server-side code.

Create an integration and key#

  1. Create an integration

    Open Admin → Integrations. Give it a name, description and role. The default is Viewer. Only roles within your own privileges are available; integrations cannot administer the organization.

  2. Create a key

    Choose New key, a name, scope and optional expiry. Copy the orbk_live_… key immediately: it is shown once and cannot be recovered.

  3. Send the key

    Add Authorization: Bearer orbk_live_… to each request. Never put a key in a URL or commit it to source control. Try the first request.

ScopeAllows
readGET requests: collections, features, tiles, content, maps, jobs and webhook listings.
read_writeGET requests plus writes allowed by the integration’s role, including uploads, exports and webhook management.

A read_write key on a Viewer integration cannot edit features. A read key on an Editor integration cannot write, but it can still expose any data that role can read. Treat both as secrets.

Note

Viewer integrations are free. An integration with a role beyond Viewer counts as a creator seat. Limits: 5 live keys per integration and 50 integrations per organization.

Rotate or stop access#

  • Rotate: create a new key, update your system, then revoke the old key. Revocation is permanent.
  • Disable: stop an integration’s keys and webhooks; re-enable it to resume. Delete: remove the integration and its keys and webhooks.
  • Revocation delay: key and tile caches can delay loss of access by a few minutes, up to six. An expired or revoked key returns 401 once caches expire.

Browsers and anonymous access#

A key sent with an Origin header is refused with 403 key_in_browser on both the API and tile hosts. For public websites, use anonymous access to published layers.

Without a credential, a request can read content exposed by published dashboards, Journeys and maps. Unavailable content returns 404. Anonymous access has a lower rate limit.

User tokens#

You can also send an OrbGIS user access token as a bearer token. It uses that person’s permissions and expires and must be refreshed. Use an integration key for unattended work.