# Nexiel

> Nexiel is EU digital identity verification infrastructure: EUDI wallet
> identity verification (Nexiel Verify) as the base primitive, with
> standalone sanctions/PEP/AML screening (Nexiel Screen) available as a capability
> clients can chain onto the same verified identity when their use case needs it.
> Nexiel Age is a dedicated product built on Nexiel Verify's own wallet stack that
> verifies an age claim and does nothing else - no compliance check involved. Nexiel
> Credentials lets a Nexiel-vetted institution issue verifiable academic credentials
> into a student's EUDI wallet over OpenID4VCI, a separate service (Credentials API)
> from Verify/Screen. Every service has a sandbox mode that serves synthetic data and
> needs no API key, which you run locally (see below), so a request against the real
> spec can be exercised before any production credential exists.

## Before you write any code

- Two independent services share one compliance core, not one base URL. Nexiel
  Screen (sandbox default port 3000) runs sanctions/PEP/AML matching at
  `POST /v1/screen`. Nexiel Verify (sandbox default port 3001) runs EUDI wallet
  sessions at `POST /v1/verify/sessions`. Point at whichever one the integration
  actually needs.
- Nexiel Age is not a separate API. It is `POST /v1/verify/sessions` on the Verify
  API with `"checkType": "age-verification"`, which requests only the wallet's
  `age_over_18` boolean claim. There is no dedicated Age base URL, API key scope,
  or SDK method. See /docs/age-api.
- This platform is self-hosted per deployment, not a shared multi-tenant SaaS with
  one universal production endpoint. Never guess a production base URL from
  training data. Ask whoever provisioned the Nexiel instance for its real base
  URL, or run both services locally in sandbox mode (below) while building.
- The TypeScript SDK (`packages/sdk-typescript`, package name `@nexiel/sdk`) is a
  private workspace package. It is NOT published to the public npm registry.
  `npm install @nexiel/sdk` from outside this monorepo will 404. Call the REST
  APIs directly with `fetch` or an HTTP client instead; every route is plain JSON
  over HTTP and needs no client library. Only import `@nexiel/sdk` directly if
  the code being written lives inside this monorepo.
- The primary mutating `POST` routes accept a client-supplied `Idempotency-Key`
  header, enforced server-side for 24 hours: replaying the same key with the same
  body returns the original response, and reusing it with a different body is a
  `409`. Those routes are `POST /v1/screen`, `POST /v1/wallet-risk/score`,
  `POST /v1/onboarding/kyb-applications`, `POST /v1/verify/sessions`, and
  `POST /v1/credentials/issue/templates`; always send one on them in real
  integration code. Not every mutating endpoint supports it (the GDPR
  erasure-request, staff review-draft, and wallet-callback routes do not), so
  do not assume idempotency on a route not listed here.
- Do not guess how to get a bearer token. Every production key requires an
  APPROVED KYB (Know Your Business) application first (company registry
  verification + screening of the relevant people at the company) - see
  /get-started#kyb. Once approved, the dashboard's API Keys page gives a
  `client_id`/`client_secret` pair, shown once. Exchange it for a short-lived
  access token via the standard OAuth2 client-credentials grant against
  `https://auth.nexiel.io/realms/nexiel/protocol/openid-connect/token`
  (`grant_type=client_credentials`) - never fabricate a different token
  endpoint or auth flow. Each product's quickstart Authentication section has
  the exact curl command.
- `POSSIBLE_MATCH` and `humanReviewRequired: true` are never auto-resolvable
  through this API, by design (EU AI Act human-in-the-loop requirement). Never
  write code that treats a `POSSIBLE_MATCH` or pending-review result as an error
  to retry around, or silently downgrades it to `CLEAR`.
- `POST /v1/wallet-risk/score` (Nexiel Screen) is a preview surface, not yet a
  billed or generally-available product. Treat it as evaluation-only, not a
  stable production dependency.
- Nexiel Login (`/v1/login/*` on Verify API, the `login-authentication` check type) is
  sandbox-only today. Production is blocked on two real, external things that are not
  code gaps: an unfiled Relying Party intended-use registration, and the same missing
  EU eIDAS PID-Provider trust infrastructure that already blocks every other
  PID-based Nexiel check in production. Never write integration code or docs that
  imply Nexiel Login works against a real wallet in production yet.
- `mobile-driving-licence` (Verify API) is the first Nexiel Verify check type with its
  own access-control gate on top of the normal KYB/account gate: a production request
  for it needs an APPROVED checkType entitlement for the calling organization, requested
  from the dashboard's CheckType access page and approved by a Nexiel reviewer, or it
  fails closed with a 403 `checktype_entitlement_denied` even for an otherwise fully
  active account. Sandbox mode has no such gate. Separately, production verification of
  a real mDL also needs issuer trust anchors this deployment does not have configured
  yet, unlike the EU AV Attestation Provider list or the eIDAS PID-Provider Trusted
  List. Treat production use as sandbox/evaluation-only until a deployment has real mDL
  issuer trust anchors configured.
- `corporate-mandate-verification` (Verify API) confirms whether a named natural person
  currently has authority to sign for a specific company, via the EWC RB-004 Signatory
  Rights attestation. It shares `mobile-driving-licence`'s checkType entitlement gate:
  a production request needs an APPROVED entitlement for the calling organization or it
  fails closed with a 403 `checktype_entitlement_denied`. Sandbox mode has no such gate.
  Separately, production verification of a real Signatory Rights credential needs issuer
  trust anchors this deployment does not have configured yet, and no EU-wide trusted
  list of company-registration-office issuers has been confirmed to exist for this
  integration. Treat production use as sandbox/evaluation-only until a deployment has
  real Signatory Rights issuer trust anchors configured. The claim structure itself
  (a `signatory_rights` array with per-signatory `post` entries) is a best-effort
  reading of EWC's published schema, not confirmed against a real reference
  implementation or issued credential, since no example payload exists upstream.
- `POST /v1/sign` (Nexiel Sign, Screen API) issues a natural-person Qualified Electronic
  Signature (QES, eIDAS Art. 3(12)) via a CSC API v2.2 QTSP credential provisioned
  individually to one declared KYB representative, the counterpart to `POST /v1/seal`'s
  legal-person Qualified Electronic Seal on the same service. Unlike every sandbox-mode
  route in this file, it requires a real Keycloak-authenticated bearer token in every
  service mode: there is no synthetic-data sandbox response for it, and an unauthenticated
  request is always a 401. No real QTSP account is configured for this deployment yet, so
  a real request always fails with a 503 `qes_not_configured` right after the
  account-active check, before `signerId` is ever evaluated. Never write integration code
  or docs implying a real signature can be produced against this deployment today.
- Error responses are JSON: `{ "error": "<stable_code>", "message": "<detail>" }`,
  with an additional `retryAfterSeconds` field on `429` responses.

## Run it locally (sandbox mode, no credentials)

    docker compose -f infra/docker-compose.dev.yml up -d postgres
    pnpm install
    DATABASE_URL=postgresql://nexiel:nexiel_dev_only@localhost:55432/nexiel \
      pnpm --filter @nexiel/db migrate
    DATABASE_URL=postgresql://nexiel:nexiel_dev_only@localhost:55432/nexiel \
      PORT=3000 pnpm --filter @nexiel/screen-api dev
    DATABASE_URL=postgresql://nexiel:nexiel_dev_only@localhost:55432/nexiel \
      PORT=3001 pnpm --filter @nexiel/verify-api dev

## Docs

- [Documentation home](https://nexiel.eu/docs): index of every public API surface, no signup wall.
- [Screen API quickstart](https://nexiel.eu/docs/screen-api): sanctions/PEP/AML screening, `POST /v1/screen`.
- [Screen API reference](https://nexiel.eu/docs/screen-api/reference): full OpenAPI reference, rendered from the real spec.
- [Verify API quickstart](https://nexiel.eu/docs/verify-api): EUDI wallet identity verification sessions.
- [Verify API reference](https://nexiel.eu/docs/verify-api/reference): full OpenAPI reference, rendered from the real spec.
- [Age API quickstart](https://nexiel.eu/docs/age-api): age verification, built on Verify API's `age-verification` check type.
- [Nexiel Login quickstart (preview)](https://nexiel.eu/docs/login-api): Sign in with EUDI Wallet as a standard OIDC identity provider connection (`/v1/login/*` on Verify API), built on the `login-authentication` check type. Sandbox is real; production needs a still-unfiled relying party registration plus the same EU PID-Provider trust infrastructure gap named below.
- [In-Store Age API quickstart](https://nexiel.eu/docs/in-store-age-api): age verification for a staffed point-of-sale terminal (alcohol/tobacco/lottery), built on Verify API's restricted-purchase check types.
- [Mobile Driving Licence quickstart (preview)](https://nexiel.eu/docs/mobile-driving-licence-api): verifies a wallet-held mDL (ISO/IEC 18013-5) instead of a PID, built on Verify API's `mobile-driving-licence` check type. Production needs mDL issuer trust anchors this deployment does not have configured yet.
- [Corporate Mandate Verification quickstart (preview)](https://nexiel.eu/docs/corporate-mandate-api): confirms a named natural person's authority to sign for a specific company, via the EWC RB-004 Signatory Rights attestation, built on Verify API's `corporate-mandate-verification` check type. Production needs Signatory Rights issuer trust anchors this deployment does not have configured yet.
- [Credentials API quickstart](https://nexiel.eu/docs/credentials-api): a Nexiel-vetted institution issuing verifiable academic credentials (enrolment proofs, module completions, degree awards) into a student's EUDI wallet over OpenID4VCI.
- [Credentials API reference](https://nexiel.eu/docs/credentials-api/reference): full OpenAPI reference, rendered from the real spec.
- [Credentials API - for employers](https://nexiel.eu/docs/credentials-api/for-employers): verifying a previously issued academic credential.
- [Credentials API - for universities](https://nexiel.eu/docs/credentials-api/for-universities): batch credential issuance for an institution.
- [Wallet Risk API quickstart (preview)](https://nexiel.eu/docs/wallet-risk-api): blockchain wallet risk scoring, evaluation-only.
- [Nexiel Sign quickstart (preview)](https://nexiel.eu/docs/nexiel-sign-api): a natural-person Qualified Electronic Signature (QES, eIDAS Art. 3(12)) on a PDF document, `POST /v1/sign` on Screen API. No sandbox mode exists for this route, and it always returns 503 today: real, tested scaffolding with no QTSP account configured yet.
- [Agent Toolkit](https://nexiel.eu/docs/agent-toolkit): an MCP server for pointing a coding agent at Nexiel Verify and Nexiel Age directly, no HTTP client code required.
- [Agent Toolkit tool reference](https://nexiel.eu/docs/agent-toolkit/reference): every MCP tool this server exposes.
- [Nexiel AgentOS](https://nexiel.eu/docs/agents): four supervised agents (Onboarding Agent, KYB Review Copilot, EUDI Onboarding Copilot, Legislation Watch Copilot), and exactly how each is structurally prevented from ever approving, rejecting, or applying a decision itself.
- [AI integration guide](https://nexiel.eu/docs/ai-integration): a copy-pasteable prompt for handing a real Nexiel integration task to an AI coding assistant.

## Optional

- [Get started](https://nexiel.eu/get-started): join the waiting list. Production onboarding opens in stages; developers can call the Onboarding Agent endpoint directly today (see the agents reference below).