Scopes & authorization

Every one of the 227 operations declares exactly one scope — a resource:action string such as items:read, orders:write, or processing:process — and before an operation runs the API checks that your principal holds it, otherwise the call is rejected with 403 Forbidden before any work happens.

How scope checks work

Each operation declares the single scope it requires; this page is the authoritative source for that mapping, and every SDK and the operation index link here. You never set scopes on a request — they are derived from your credential, a minted API key or a session token (obtained by signing in to Geopera), and checked automatically.

The API resolves a principal from your Authorization bearer, computes the set of scopes that principal holds, and then, for the operation you invoked, runs a single check:

if not principal.has_scope(op.required_scope):
    raise ScopeDenied(f"missing scope {op.required_scope!r} for {operation_id!r}")

has_scope grants a required scope by any of:

• an exact match — the principal holds items:read and the op requires items:read;
• a full wildcard — the principal holds * (service-role / internal only);
• a resource wildcard — items:* satisfies items:read, items:write, and any future items: action;
• an action wildcard — *:read satisfies items:read, catalog:read, and every other :read.

So the unit you are granted is usually a wildcard (e.g. items:* or *:write), and the unit an operation requires is always a concrete resource:action. The scope check is purely about capability — owning items:read does not grant you access to another org’s items. Per-resource ownership (does this item belong to your project / organization?) is enforced separately inside each operation and surfaces as its own 403/404. See Concepts for the principal model and Errors for the failure shapes.

The action verbs

Across the whole surface there are four actions. The action is encoded in the operation name, never in an HTTP verb — every operation is a POST /v1/op/{operation_id}.

process and destroy are separated from write deliberately: launching billable compute and tearing down job artifacts are higher-consequence than ordinary mutations, so a key can be granted writes without being granted the ability to spend on processing or to destroy jobs.

Scope catalog

Below is every scope, grouped by resource domain. The Ops column is the count of operations gated by that scope; representative operation IDs follow. Resource domains marked privileged are not part of the self-serve surface — see Privileged scopes.

Imagery & catalog

Note that stac.* and the read-only orders.estimate / orders.get_schema / orders.list_assets operations live under items:read, and the glossary.* reference operations live under catalog:read. Visualization profile reads use items:read; profile writes use items:write; the cross-item visualization.list_for uses tiles:read.

Orders & tasking

Every order operation — including reads like orders.tasking.feasibility_check — gates on orders:read, so a key that can place orders also needs read to walk the workflow. Write/process keys are granted read automatically (see below), so this is transparent for API keys.

Processing, analytics & clips

clip.create_from_item sits under processing:process (it launches compute against an item), while clip.create_from_area sits under clip:write. The clip:* resource is privileged — see below.

Uploads, provenance, reports & usage

Projects & organizations

There is no projects:read scope: project reads are folded into the resources they return (items, orders, jobs). Membership in the project or organization is still enforced per-operation.

Sharing, alerts, events & notifications

Billing, EULAs & API keys

Privileged scopes

The clip resource is not part of the self-serve surface. clip scopes are granted only to the designated clip user — a normal API key never inherits them through a broad capability, and a member never gets them from ordinary membership.

Geopera also runs administrative and internal operations (billing reconciliation, data retention, scheduled jobs, and the like). These require an admin:* scope that is never granted to customer API keys or ordinary members, so they are omitted from this reference; calling one with a customer credential returns 403.

How credentials map to scopes

Your scope set is derived from the kind of principal behind your bearer token.

API keys

A minted API key (prefix gpra_) carries up to three capability flags, set when the key is created:

These expand to action-wildcard scopes over the self-serve resources. A key with can_read holds the equivalent of *:read; a key with can_write holds *:write; a key with can_process holds *:process — but only over non-privileged resources. Critically, an API key can never reach admin:* or clip:* through these capability flags, no matter how broad. A privileged resource is reachable by a key only through an explicit stored scope provisioned on the key itself.

Two convenience rules:

• A key with no capabilities still gets read (the floor), so every key can at least list and get.
• can_write or can_process imply can_read. A write/process key can also estimate, list, and walk read steps of a workflow, so a single key runs an end-to-end flow (for example, the whole order workflow gates on orders:read even for its write steps). You do not need to grant read separately.

# A key created with can_read + can_process holds, effectively:
#   *:read   (every non-privileged :read scope)
#   *:process (every non-privileged :process scope)
# It can search the catalog, launch processing, and list jobs —
# but it cannot orders.place (needs orders:write) and cannot
# touch any admin:* or clip:* operation.

curl -s https://api.geopera.com/v1/op/processing.create \
  -H "Authorization: Bearer gpra_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"project_id": "...", "job_type": "ndvi", "item_ids": ["..."]}'

Session tokens (human users)

A human user authenticated with a session token (obtained by signing in to Geopera) receives the full self-serve standard set: one {resource}:* wildcard for every non-privileged resource. In practice a logged-in member can invoke any non-admin, non-clip operation their org and project membership allow — the scope check is satisfied, and access is then narrowed to their resources by the per-operation ownership checks.

On top of that floor:

• The designated clip user (a configured account) additionally holds clip:*.
• A system admin additionally holds admin:* and clip:*.

Project and organization roles (owner, admin, member) do not change your scope set — they govern per-resource ownership and the privileged role checks inside individual operations (for example, only an org admin/owner can run organization-admin operations). Scopes answer “can this principal perform this class of action at all?”; roles and membership answer “on this specific resource?“. Both must pass.

Workers and service-role

Internal worker tokens hold exactly processing:process — enough to register their own job’s outputs and nothing else. The service-role identity holds * (full trust) and is for internal/system use only. Neither is something you provision; they are listed for completeness.

What a denied call returns

A missing scope produces an RFC 9457 problem+json response with status 403:

POST /v1/op/orders.place HTTP/1.1
Host: api.geopera.com
Authorization: Bearer gpra_a_read_only_key
Content-Type: application/json

{ "project_id": "...", "items": ["..."] }

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://api.geopera.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "missing scope 'orders:write' for 'orders.place'"
}

The detail names the exact scope you lacked and the operation you called, so you can read off precisely which capability or role is missing. The check runs before any side effect — a denied write never mutates state and is never billed.

Distinguish this from the other 403 you can receive: an ownership failure. If you hold items:read but ask for an item in another organization’s project, the scope check passes and the operation’s own ownership check raises a 403 with a detail like Access denied. Same status, different cause — the detail tells them apart. See Errors for the full taxonomy.

Gotchas

• One scope per operation. Operations never require two scopes. If a call needs both reading and writing (e.g. an order workflow), each underlying operation has its own single scope; you hold the union across your credential.
• The action lives in the name, not the verb. items.delete is items:write, not a DELETE. Always POST /v1/op/{operation_id}. There are no GET/PUT/PATCH/DELETE operations.
• process and destroy are not write. A can_write key cannot launch processing (processing:process) or delete a job (clip:destroy) unless it also has can_process / an explicit destroy scope.
• Capability flags can’t reach privileged scopes. No combination of can_read/can_write/can_process grants admin:* or clip:*. That is by design to prevent cross-tenant escalation.
• Scope ≠ ownership. Passing the scope check does not mean you can touch a given resource. Membership and role checks run per-operation and surface their own 403/404.

Related

• Authentication — bearer tokens, the gpra_ API-key prefix, and minting keys with capabilities.
• Concepts — the principal model and the operation-name convention.
• Errors — the full problem+json taxonomy, including the two 403 causes.
• Operations — the complete operation index, each linking back to its scope here.