Authentication

Sarkoa uses session-based sign-in for the web app and API keys for programmatic access.

flowchart TB
  User[User]
  Web[Web app session]
  Key[API key]
  Tools[CLI and QGIS]
  PubAPI[Public API]
  User --> Web
  User -->|Profile API and Integrations| Key
  Web --> Tools
  Key --> Tools
  Key -->|Bearer sk_...| PubAPI

Web sign-in

Sign in to the Sarkoa web app with your account. Sessions are used for browsing files, maps, billing, and creating API keys. Open the app from Sign in or Get started on sarkoa.com.

API keys

Create and revoke keys in the web app under Profile → API & Integrations. That page also links to CLI, MCP, QGIS, and Skills setup docs. Use the smallest scope your integration needs.

CLI, QGIS, and MCP

Keys used by the CLI, QGIS plugin, and hosted MCP. Pass the key as a Bearer token (CLI: SARKOA_API_TOKEN or sarkoa config set token; MCP: Authorization: Bearer … in the agent config).

To confirm a key works, call GET /api/me on the app host (for example https://app.sarkoa.com/api/me) with Authorization: Bearer <your_api_key>. A successful response includes your email, organization, scopes, and auth: "api_key". The same check is what sarkoa whoami uses.

These keys support exactly two scopes (select one or both when creating the key):

Grant write only when uploads or deletes are required. A key needs at least one of these scopes.

Public API

The public API at api.sarkoa.com is available on Essential plan and above. Create Asset API keys under API Routes in the web app. Keys authenticate with Authorization: Bearer sk_.... These keys support exactly two scopes (select one or both when creating the key):

Below Essential, public API calls return 403 with code: plan_upgrade_required.

Asset API keys also accept ?api_key=sk_... as a query parameter, for clients that cannot set a header. Prefer the Bearer header: a key in a query string is recorded in server logs, proxy logs, and browser history, and is far easier to leak by accident.

The two key types are not interchangeable. A Profile key will not fetch tiles from api.sarkoa.com, and an Asset API key will not manage files. If a call fails with 401 on a key you know is valid, check you are using the right kind for that host: API reference has the split.

Organization ID for CLI and QGIS

Usually unnecessary, each API key already targets one organization. Required for CLI download-bulk, which is the one command an API key cannot authenticate at all: it goes through the manifest API, which accepts a signed-in session only and returns 403 to a key. Details: CLI → Environment variables.

Security tips

• Never commit API tokens to git or paste secrets into tickets or chat
• Rotate keys if a machine or teammate loses access
• Use a separate API key per organization