Cloud API

The digid cloud endpoints your app and backend call, and where the full API reference lives.

The digid cloud never sees a card, a face or a result. Your app or backend calls it for two things: usage reports and licence renewal. Your backend can also manage licences and keys with an API key.

The full, generated reference of every endpoint is at /api/docs, and the machine-readable OpenAPI description at /api/openapi.json.

Base URL

https://digid.co.tz/api/v1

Requests and responses are JSON. Errors have one shape:

{ "error": { "code": "usage_report_missing", "message": "…", "details": { "missing_days": ["2026-10-28"] } } }

Called by the SDK's reports (no API key)

These two endpoints take what the SDK builds. The licence key inside authenticates each one, so your app can call them directly, or your backend can relay them server to server. To your code the bodies are opaque text.

POST /usage

A daily usage report: counts only.

POST /api/v1/usage
Content-Type: application/json

{ "report": "digidusage1.…" }

200 with the recorded day and count. Posting the same day again replaces its count; it never lowers it.

POST /licences/renew

Renews a key from a phone (pay as you go). The request carries the phone's usage reports.

POST /api/v1/licences/renew
Content-Type: application/json

{ "request": "digidrenew1.…" }

201 with the new key:

{ "data": { "object": "licence_token", "licence_id": "lic_…", "plan": "payg", "token": "digidlic1.…",
            "issued_at": "2026-10-30T08:00:00Z", "expires_at": "2026-11-06T08:00:00Z" } }

The SDK's renewLicence reads this for you. Refusals (usage_report_missing, insufficient_credit, …) are in Error codes, and the rules in Licences and renewal.

With an API key (your backend)

Create API keys in the customer portal. Send them as a bearer token from your backend only, never from an app or a web page.

Endpoint	Use
`GET /licences`	Your licences
`GET /licences/:id`	One licence: its apps, features and dates
`POST /licences/:id/tokens`	Issue a fresh licence key, for example to rotate keys from your backend. For pay-as-you-go licences, at most once every 30 days (`bootstrap_limit`).

The API also covers your organisation, team and audit trail. See /api/docs for every endpoint, its parameters and scopes.