API Specification

1. Overview

This document defines the MyFace Biometric Sovereignty Standard API — the technical specification for a decentralised, open standard biometric sovereignty registry. It is intended for developers, standards bodies, and organisations implementing compatible systems.

The API is designed around three core principles:

• Minimal data. Return only what is necessary. Never expose raw biometric data.
• Decentralised trust. No single authority controls the system. Trust is cryptographic, not institutional.
• Full auditability. Every API call is logged immutably. The audit trail is accessible to citizens, entities and governance bodies.

2. Technical Foundation

2.1 Transport

• HTTPS only. TLS 1.3 minimum.
• All requests and responses in JSON (application/json).
• Standard HTTP status codes for all responses.

2.2 Versioning

All endpoints are prefixed with the API version. The current version is v1. Version increments are additive where possible. Breaking changes require a new version prefix. Previous versions are supported for a minimum of 24 months following deprecation notice.

Base URL: https://api.biometricsovereigntystandard.org.uk/v1/

2.3 Identity — The UID

Every registered citizen is assigned a globally unique identifier. The UID is jurisdiction-prefixed to support international interoperability.

• Format: {ISO-3166-1-alpha-2}-{16-char-hex}
• Example: GB-a3f9c2d1e4f5b6c7

The UID is derived from a one-way cryptographic hash of the citizen's biometric data combined with a jurisdiction-specific salt. It cannot be reversed to reconstruct the original biometric.

2.4 Entity References

Registered commercial entities are identified by a 64-character hex string — a SHA-256 hash generated from the entity's verified registration details at the point of registration.

• Format: 64-character hex string (SHA-256)
• Example: 7f83b1657779fc7d3a73d8d5c0a7b3d4e2f1a9c6b8e4d2f0a1c3e5b7d9f2a4c6

Entity references are opaque by design. Actual entity details are held in the registry and accessible only through authenticated governance endpoints.

2.5 Authentication — Verifiable Credentials

The MyFace Biometric Sovereignty Standard uses W3C Verifiable Credentials (VC) for entity authentication. This standard was chosen for its decentralised architecture — no central authentication server is required and credential validity can be verified by any node against the public blockchain.

Authentication flow:

• Entity registers and receives a VC signed by the Authority's private key.
• The Authority's public key is published on the blockchain, verifiable by any node.
• Each API request includes the entity's VC as a Bearer token.
• The receiving node validates the VC signature against the blockchain.
• Revoked entities appear on a revocation list on the blockchain — immediately invalid across all nodes.

Authorization header format:

Authorization: Bearer {base64-encoded-verifiable-credential}

2.6 Rate Limiting

Rate limits are enforced per entity credential and returned in response headers:

• X-RateLimit-Limit — requests permitted per hour
• X-RateLimit-Remaining — requests remaining in current window
• X-RateLimit-Reset — Unix timestamp when the window resets

3. Endpoints

3.1 Verify Biometric Status

The core endpoint. Called by commercial entities before processing any biometric. The entity submits the biometric data and receives back a single-use, time-limited token. The biometric itself is never stored by the calling entity — it is submitted, checked, and discarded. The token is the only artefact retained, and it contains no personally identifiable information.

If law enforcement subsequently has legitimate reason to identify the person behind a token, they may present that token to the governance identify endpoint with appropriate judicial authorisation. The commercial entity never has access to the identity — only to the token.

{
  "biometric_data": "base64-encoded-biometric-representation",
  "purpose": "retail_loss_prevention"
}

{
  "status": "protected",
  "permitted": false,
  "token": "a9f3c2e1b4d7f0a8c5e2b9d6f3a0c7e4...",
  "token_expires": "2026-03-21T16:05:00Z",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

Status values:

3.2 Get Identity Status

Returns full status for a citizen. Authenticated citizen access only.

{
  "uid": "GB-a3f9c2d1e4f5b6c7",
  "protected": true,
  "permitted_entities": [
    "7f83b1657779fc7d3a73d8d5c0a7b3d4e2f1a9c6b8e4d2f0a1c3e5b7d9f2a4c6"
  ],
  "jurisdiction": "GB",
  "last_updated": "2026-03-21T09:00:00Z"
}

3.3 Grant Permission

Citizen grants permission to a specific registered entity for a specific purpose.

{
  "entity_ref": "7f83b1657779fc7d3a73d8d5c0a7b3d4e2f1a9c6b8e4d2f0a1c3e5b7d9f2a4c6",
  "purpose": "retail_loss_prevention",
  "expiry": "2027-03-21T00:00:00Z"
}

3.4 Revoke Permission

Citizen revokes a previously granted permission. Immediate effect across all nodes.

{
  "entity_ref": "7f83b1657779fc7d3a73d8d5c0a7b3d4e2f1a9c6b8e4d2f0a1c3e5b7d9f2a4c6"
}

3.5 List Permissions

3.6 Register Entity

Registers a commercial entity. Requires prior approval from the MyFace Authority.

{
  "legal_name": "Example Retail Ltd",
  "jurisdiction": "GB",
  "registration_number": "12345678",
  "permitted_purposes": ["retail_loss_prevention"],
  "public_key": "-----BEGIN PUBLIC KEY-----..."
}

3.7 Get Entity Status

3.8 Governance Identify

Allows an authorised government body to resolve a token issued by the verify endpoint back to a UID. This is the only mechanism by which a commercial verification event can be connected to an identity — and it requires judicial authorisation.

The commercial entity that received the original token has no access to this endpoint and no means to resolve the token to an identity themselves. The separation is architectural, not merely policy.

{
    "token": "a9f3c2e1b4d7f0a8c5e2b9d6f3a0c7e4b1d8f5a2c9e6b3d0f7a4c1e8b5d2f9a6",
    "warrant_reference": "WARRANT-2026-GB-00142",
    "legal_basis": "serious_crime_investigation",
    "requesting_officer": "badge-credential-hash"
  }

{
  "uid": "GB-a3f9c2d1e4f5b6c7",
  "jurisdiction": "GB",
  "token_issued_at": "2026-03-21T15:58:42Z",
  "token_issued_to_entity": "7f83b1657779fc7d3a73d8d5c0a7b3d4e2f1a9c6b8e4d2f0a1c3e5b7d9f2a4c6",
  "request_id": "governance-audit-ref"
}

Legal basis values:

4. Audit Trail

Every API call is logged immutably to the blockchain. The audit trail is accessible to three audiences, each with appropriate scope:

4.1 Citizen Audit

4.2 Entity Audit

4.3 Governance Audit

4.4 Public Audit Summary

5. Error Responses

All errors return a consistent JSON structure. Errors must be surfaced clearly — a protected biometric processed due to a suppressed error is a protocol violation.

{
  "error": "error_code",
  "code": 403,
  "message": "Human readable description.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}

6. Implementation Notes

6.1 Default to Protection

6.2 Node Redundancy

Implementing systems should maintain a list of available nodes and retry failed requests against alternative nodes before returning an error. No single node failure should result in a system-wide outage.

6.3 Biometric Data Submission

The biometric data submitted to the verify endpoint must conform to the MyFace Biometric Sovereignty Standard canonical representation specification. This defines the format, encoding and normalisation of facial biometric data to ensure consistent processing across all implementing systems. The canonical representation specification is published separately at biometricsovereigntystandard.org.uk/spec/biometric.

6.4 Purpose Codes

The purpose field must use a registered purpose code from the MyFace Biometric Sovereignty Standard purpose registry at biometricsovereigntystandard.org.uk/spec/purposes. Current registered purposes:

• retail_loss_prevention
• access_control
• age_verification
• event_ticketing

6.5 International Interoperability

Partner nation implementations must implement the full v1 API specification without modification to core endpoints. A citizen registered under any partner jurisdiction can be verified by any compliant node. The jurisdiction prefix in the UID routes queries to the appropriate national registry.

7. Changelog

v1.0 — March 2026
Initial specification published.