Authentication
PATENT PENDING — Ma'atara Protocol. Reviewed 21 September 2026.
Protected native APIs require a signed assertion and current lifecycle authority. Human sign-in sessions are not substitutes. Public reads and route-specific service credentials are separately documented in Public API surface.
Authorization: MaataraAssertion <assertionB64u>.<signatureB64u>
Use the approved identity integration's assertion issuer. Keep private keys at the endpoint and never cache bearer assertions. Quickstart illustrates version 1.
Version-1 root assertion
| Field | Required | Meaning |
|---|---|---|
version | yes | 1 |
purpose | yes | Exact literal auth/session |
userId | yes | Canonical identifier supplied by the identity session |
chainId | yes | Owner ML-DSA-65 public key, base64url |
publicChainKey | yes | Same public key as chainId |
issuedAt | yes | Epoch milliseconds |
expiresAt | yes | Epoch milliseconds; validity at most one hour |
nonce | yes | Fresh non-empty single-use value |
aud | yes | Exact destination route/service audience |
deviceId | no | Device hint; does not confer device authority |
scopes | no | Scope hints; do not override route authorization |
The toolkit sign/verify methods accept base64url-encoded message bytes. For assertions, preserve the transmitted JSON bytes; do not reserialize the payload in transit or apply a record-signing recipe to it. The signature algorithm is ML-DSA-65.
Use SDK identity helpers instead of reproducing derivation. The verifier checks that the identifiers, signing key and claimed identity agree and that the current lifecycle allows the operation. A mathematically valid signature is not sufficient by itself.
Replay, time and audience
A nonce is consumed on authorization, including reads. Mint a new assertion for every request, retry and destination. Reuse returns an authorization failure, including assertion_replay on shared verification paths.
Version-1 Core accepts up to two minutes of clock skew; the shared version-1 verifier allows up to five. Both cap validity at one hour. Use a short validity window and keep clocks accurate.
Audience matching is exact. There are no wildcards or unscoped native fallbacks. Use the audience table; Core route groups use different audiences. Some destinations impose additional nonce length/character restrictions.
Version-2 device assertions
Device verification is implemented. Checked source configuration enables DEVICE_KEYS_VERIFY = "1" for production Core, Aegis and the DID resolver. This configuration is not, by itself, a live deployment receipt.
A device assertion is issued by an authorized device session and is bound to the attested device, origin, root epoch and capabilities. Verifiers check expiry, revocation and current authority as well as signature, audience and nonce. Never substitute a device key in a root assertion or copy a recovery phrase as an automatic fallback.
A deployment with device verification disabled refuses device assertions with device_keys_disabled. Delegation-aware root rotation has a separate gate; enabling device verification does not enable that rotation flow or experimental messaging.
DID resolution
Method and path on did.ma-atara.io | Purpose |
|---|---|
GET /health | Liveness and service identity |
GET /.well-known/did.json | Resolver self-description |
GET /1.0/identifiers/:did | Registered DID resolution result |
GET /1.0/identifiers/:did/bindings | Owner-authenticated member bindings |
POST /1.0/register | Owner-authenticated registration |
/1.0/org/* | Route-specific organization operations |
Malformed DIDs return 400; unresolved valid DIDs return 404; deactivated DIDs return 410. Resolution uses current user-key authority evidence, not a registry-free key-presented fallback. The resolver's standards-shaped response is not an endorsement or certification claim.
Human onboarding is provided through id.maatara.io and the authentication service. Passkey custody properties depend on the authenticator; browser/WASM signing is not automatically hardware-bound. Temporary legacy account healing is retired (HTTP 410).