API for integration & automation

1. Authentication

All endpoints use bearer tokens scoped to a single tenant (organisation). Each token represents a user in that tenant and inherits its roles and permissions.

1.1 Login

Form-based login using email and password. Returns an access_token which must be sent as Authorization: Bearer <token> header on all subsequent calls.

POST /login
Content-Type: application/x-www-form-urlencoded

username=<email>&password=<password>

# response (example)
{
  "access_token": "eyJhbGciOiJIUzI1...",
  "token_type": "bearer"
}

1.2 Tenant scoping

Each user belongs to exactly one tenant (manufacturer / importer / distributor / integrator). All API calls are automatically scoped to that tenant; there is no cross-tenant access.

2. Core objects

2.1 Products

Products represent the hardware / software items that fall under the EU Cyber Resilience Act.

Returns all products in the current tenant account.

GET /products
Authorization: Bearer <token>

# response (simplified)
[
  {
    "id": 1,
    "brand": "DemoBrand",
    "model_name": "DemoModel 100",
    "sku": "DEMO-100",
    "product_family": "Demo Family",
    "cra_category": "normal",
    "status": "on_market"
  },
  ...
]

Creates a new product within the tenant.

POST /products
Authorization: Bearer <token>
Content-Type: application/json

{
  "brand": "DemoBrand",
  "model_name": "New Model",
  "sku": "NEW-001",
  "product_family": "Family X",
  "description": "Optional description",
  "cra_category": "normal",
  "status": "in_development"
}

2.2 Compliance documents

Documents such as security policies, test reports, vulnerability handling processes and declarations of conformity can be linked to products and CRA dossiers.

Implementation details for document upload (multipart/form-data vs. external object storage) may differ per deployment. For the public demo environment, this endpoint is intentionally limited.

2.3 CRA checklist & tasks

Internally, the portal tracks CRA readiness using a structured checklist and task/incident entities. These APIs are typically used by the web frontend and not exposed directly to third-party systems in the first release.

3. Partner & white-label API

For distributors and solution partners, CRA-Portal can be offered as a white-label service. Each partner can onboard multiple OEMs while keeping data strictly separated per tenant.

3.1 Concept: partner API

The partner API is designed for machine-to-machine integrations (for example, an OEM portal or a distributor dashboard pushing product metadata into CRA-Portal).

A typical design is:

• Each OEM or partner tenant receives one or more API credentials.
• Authentication using client_id and client_secret.
• Rate limiting and access control based on subscription plan.

3.2 Example partner flow (planned)

Example for a simple product sync integration:

# 1) Partner obtains API credentials from CRA-Portal operator
client_id = "..." 
client_secret = "..."

# 2) Partner backend syncs products to CRA-Portal
#    (pseudo-code, actual endpoint may differ per deployment)

POST /partner-api/products/sync
Authorization: Basic <client_id:client_secret>
Content-Type: application/json

{
  "products": [
    {
      "external_id": "OEM-123",
      "brand": "BrandX",
      "model_name": "Router 2000",
      "sku": "RX-2000",
      "cra_category": "critical"
    },
    ...
  ]
}

In the current demo environment, partner APIs are under active development. The concrete endpoint set and authentication scheme (Basic vs. OAuth2 client credentials) will be aligned with partner requirements during onboarding.

4. Environment & stability

The CRA-Portal backend runs as a containerized FastAPI service with PostgreSQL as primary datastore. API changes are versioned and backwards-compatible paths are preserved where possible.

• Transport security via HTTPS (terminated at reverse proxy / CDN).
• Per-tenant isolation enforced at application-layer (tenant_id).
• Rate limiting and quota per subscription plan are supported.