Reference

Atlas Core API.

One general Core that every project builds on, surfaced as REST + webhooks (gRPC internally). Auth is DID-SSO (Numira as IdP) or a scoped API key — the same model as the rest of the HARA stack. Per-line SDKs add only domain verbs on top.

Base · https://api.atlas.haratrust.io/v1Local · http://localhost:3000/api/v1Chain · 131216

Authentication

DID-SSO or a scoped key.

DID-SSO (Login with Numira)

Standard OIDC Authorization-Code + PKCE against Numira's dSSO bridge. Verify the id_token (EdDSA) against the JWKS; sub is the user's alias DID. Pass it as a bearer token to the Core.

Authorization: Bearer <numira_id_token>

Scoped API key (server-to-server)

Per-tenant key issued in Atlas Ops, metered per call. For SAP / customs / registry integrations.

X-Atlas-Api-Key: <tenant-key>

Endpoints

The Core surface.

Objects & passports

POST	/objects	Create an object (class, classification, ownerDid) → Object DID + draft passport
GET	/objects/{pid}	Resolve a passport (public fields) — used by Public Verify, no login
POST	/objects/{pid}/seal	Pin requirements + dual-anchor (PQAnchorRegistry + optional record NFT)
POST	/objects/{pid}/revoke	Burn the record NFT + freeze any value token

Credentials & consent

POST	/credentials	Issue a role VC — you build the unsigned VC, Numira signs it (eddsa-jcs-2022)
GET	/objects	List passports (paginated: ?page=&pageSize=)
POST	/credentials/verify	Verify a VC against Numira (signature + Bitstring Status List + anchor)

Motions — Locate · Trace · Certify

POST	/objects/{pid}/locate	Attach point/parcel geolocation (+ anti-spoof score)
POST	/objects/{pid}/trace	Append a journey/transformation event (mass-balance enforced)
POST	/objects/{pid}/certify	Attach a certification credential against a Standard schema

The two ratings & Mint

GET	/objects/{pid}/rating?kind=identity	Identity-strength score + assurance level (0–100 + A1–A4)
GET	/objects/{pid}/rating?kind=value	Value/risk grade (AAA–D / 0–100) + SHAP drivers
POST	/objects/{pid}/mint	Mint the token class for the object
GET	/recognition/route	Field-level recognition delta between two authorities/standards

SDK

@hara/atlas-core.

A typed client that mirrors Numira's NumiraClient — same constructor, same error model. One package, every motion.

import { AtlasClient } from "@hara/atlas-core";

const atlas = new AtlasClient({
  baseUrl: "https://api.atlas.haratrust.io/v1",
  apiKey: process.env.ATLAS_API_KEY,           // or authToken: a Numira DID-SSO id_token
});

const obj = await atlas.objects.create({ class: "commodity_lot", ownerDid });

await atlas.locate.parcel(obj.did, { geohash });
await atlas.trace.event(obj.did, { eventType: "transform" });
await atlas.certify.issue(obj.did, { role: "trade", issuer: "Customs", standard: "EUDR", issuerDid });

const identity = await atlas.rate.identity(obj.did);   // 0–100 + A1–A4
const value    = await atlas.rate.value(obj.did);      // AAA–D + drivers

await atlas.objects.seal(obj.did);
await atlas.mint.token(obj.did, { mode: "lot" });

Try it

Resolve a passport with curl.

curl -s http://localhost:3000/api/v1/objects/did:hara:obj:lot:01J7CPO

# → { "did": "did:hara:obj:lot:01J7CPO", "status": "sealed",
#     "ratings": { "value": { "band": "AA", "score": 86, "drivers": [ … ] } },
#     "anchors": { "chain": "131216", "pqAnchorId": 4211, "merkleRoot": "0x…" }, … }

That endpoint is live in this demo (mock-backed). In production it proxies the Core service, which reads Postgres and verifies anchors against PQAnchorRegistry on chain 131216.

Errors

Conventional, machine-readable.

Non-2xx returns { "error": "<code>", "detail"?: "<message>" } and the SDK throws AtlasError(status, code, detail) — tolerant of both the current envelope and RFC 7807 problem+json.

Status	Common codes
400	bad_request · invalid_class · unsupported_proof_type
401	invalid_api_key · unauthorized
403	consent_revoked · not_allowed
404	object_not_found · credential_not_found
409	already_sealed · polygon_overlap

Line endpoints

Each line adds domain verbs.

GET	/trace/batches/:id/epcis	EPCIS 2.0 + GS1 Digital Link provenance export
POST	/halal/verify-cert	Halal certificate-VC trust chain (binary gate)
GET	/rwa/assets/:id	RWA gold multidimensional rating + NAV
GET	/land/hpl/:id	HPL lifecycle + PTSL title integrity
GET	/carbon/credits/:id	ICVCM CCP integrity grade + registry cross-check
POST	/cred/credentials/:id/verify	Credentials A1–A4 recognition gate
GET	/art/works/:id	Art assurance-of-evidence (six axes) + provenance
GET	/location/places/:id	Place DID + geofence + anti-spoof
GET	/governance/models	SR 11-7 model cards
POST	/governance/rating-credential	Export a rating as a VCDM RatingCredential
GET	/ops/ingestion	Data-spine connector freshness / N-A / mock-vs-live

SDKs

TypeScript today, Python alongside.

The TypeScript SDK lives in packages/atlas-core. A requests-based Python SDK is in clients/python:

pip install -e clients/python

from hara_atlas import HaraAtlas
atlas = HaraAtlas("https://atlas.stg.haratrust.io", api_key="...")
obj = atlas.objects.create(object_class="commodity_lot",
    owner_did="did:hara:org:gar", label="CPO batch")
atlas.certify(obj["did"], role="origin", issuer="RSPO",
    standard="RSPO", claims={"cert": "RSPO-1"})
print(atlas.rate(obj["did"]))  # {'identity': {...}, 'value': {...}}

A Kotlin SDK is on the roadmap (CORE-3).