Terrakio Admin API Client

Administrative API client for Terrakio services. This package extends the regular Terrakio API client with additional administrative capabilities.

Features

• All features from the regular API client
• User management (list, inspect, restrict, delete accounts)
• Service accounts
• Dataset management (create, edit, update, delete datasets)
• Mass stats functionality (create pyramid)

Installation

pip install terrakio-admin-api

Usage Example

from terrakio_admin_api import Client

admin_client = Client()  # defaults to https://api-candidate.terrak.io (fronts all regions)
# or name an environment: Client(env="prod" | "candidate" | "dev" | "local" | …),
# settable for a whole session with TERRAKIO_ENV

admin_client.auth.login(email="XXX", password="XXX")

datasets = admin_client.datasets.list_datasets()
users = admin_client.users.list_users()

Signing in, API keys and credential precedence work as they do in terrakio-api. admin_client.keys manages another account's keys by passing uid=.

Service accounts

A service account has no password and cannot log in. Its keys are managed by the group named in managed_by, whose owner and members mint and revoke them.

account = admin_client.users.create_service_account(
    email="ingest@example.com", managed_by=group_id
)
key = admin_client.keys.create_key(label="ingest", uid=account["uid"])

# Hand it to another group
admin_client.users.set_managed_by(uid=account["uid"], group=other_group_id)

There is no way to convert an existing account into a service account: that would also have to disable its Identity Platform login, which the user endpoints do not do.

Restricting an account

# Leave the account only the datasets its own groups reach
admin_client.users.set_public_access(uid=uid, allowed=False)
# ... with named exceptions (exact dataset names, no patterns)
admin_client.users.set_public_access(uid=uid, allowed=False, allowed_datasets=["MSWX"])
# Back to the public catalog, exceptions cleared
admin_client.users.set_public_access(uid=uid, allowed=True)

# Only these origins may present this account's API keys
admin_client.users.set_allowed_origins(uid=uid, origins=["https://app.example.com",
                                                         "https://*.example.com"])
admin_client.users.set_allowed_origins(uid=uid, origins=[])    # nothing at all
admin_client.users.set_allowed_origins(uid=uid, origins=None)  # no restriction

Origins are scheme://host[:port] or scheme://*.domain[:port]; a wildcard covers subdomains only, so list the apex domain separately. A restricted account is browser-only by declaration: a request that states no origin is refused, and the server falls back to the Referer header when there is no Origin, so a site sending Referrer-Policy: no-referrer will be locked out of its own key.

get_user_by_id prints the whole account document, these fields included.

Groups

The owner-scoped group methods are the same as in terrakio-api. The admin mirrors reach every group, whoever owns it: list_groups_admin, get_group_admin, create_group_admin(name, owner) and delete_group_admin.

Writing a dataset

A dataset document states its kind — stored (data in a store), computed (an input expression bound to a registry function) or loader (served by a loader module). Storage presence says where a stored dataset is available: bucket for the cloud, mount for the on-prem cluster, either or both. Pyramid settings go in zoom, serve-time settings in serving, and the grid in grid.

admin_client.datasets.create_dataset(
    name="Rainfall", kind="stored", products=["total"], dates=["2024-01-01"],
    bucket="terrakio-mass-requests", path="rainfall/%s_%s_%03d_%03d_%02d.snp",
    data_type="float32", no_data=-9999, x_size=400, y_size=400, i_max=10, j_max=10,
    grid={"geotransform": geot, "proj4": proj4}, zoom={"max_zoom": 0},
)

admin_client.datasets.create_dataset(
    name="ForestCNN", kind="computed", products=["prob"], dates=["2024-01-01"],
    input="S2v2.red@(year={year})", function="forest_cnn", padding=16,
)

The payload is checked against the schema for its kind before the request, so an off-schema or misplaced field is named locally. get_dataset and list_datasets hand back this same shape whichever shape the service stores; pass raw=True for the stored document verbatim.

For more documentation, see the main repository.