Metadata-Version: 2.5
Name: terrakio-admin-api
Version: 0.13.0
Summary: Admin version of the terrakio-python-api
Requires-Python: >=3.11
Requires-Dist: terrakio-core==0.13.0
Description-Content-Type: text/markdown

# 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

```bash
pip install terrakio-admin-api
```

## Usage Example

```python
from terrakio_admin_api import Client

admin_client = Client()  # defaults to https://dev-omni.terrak.io (fronts all regions)
# or name an environment: Client(env="prod" | "candidate" | "dev-au" | "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.

```python
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

```python
# 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`.

```python
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](https://github.com/HaizeaAnalytics/terrakio-python-api).
