SDK Documentation — ELYSÉA CERVEAU

The SDK technical reference.
Everything you need to integrate, nothing more.

Authentication, API surface, 8 Guardian prohibitions, tiers, trust mark, sandbox, and error codes. Source: frozen SDK canons. Writing tooled by AI agents under the founder’s direction, under a proof protocol: tests, continuous integration, verifiable fingerprint.

Quickstart Download docs (PDF)SDK & Pricing

Builder tools

AVAILABLEOpenAPI specification
AVAILABLEFull documentation for coding assistants (llms-full.txt)
AVAILABLEHMAC-signed Postman collection
AVAILABLE“Powered by ELYSÉA” logo kit and usage rules

The widget talks to your gateway (@elysea/gateway package), which holds the secret key; the publishable pk_ key is issued by that gateway. The file is served by jsDelivr from the npm package, at a pinned version, with its integrity hash (SRI).

No version is served: @elysea/widget 0.4.0 must be published on npm (Sébastien’s action); the published version 0.3.1 points to non-existent domains and is refused.

§1 — Authentication

Test key sk_test_

Sandbox only. No real user data. No active-user billing. All Guardian prohibitions are active (sandbox is a compliance test, not a permissive mode).

Production key sk_live_

Production only. Active-user billing (LLM tokens remain the builder's responsibility — Decision KJ). An sk_test_/sk_live_ mismatch is rejected by the Core at authentication — AUTH_UNAUTHORIZED (HTTP 401).

typescript

import { createElyseaClient } from '@elysea/core';

const elysea = createElyseaClient({
  baseUrl:     process.env.ELYSEA_BASE_URL!,
  auth: { apiKey: process.env.ELYSEA_API_KEY!, apiSecret: process.env.ELYSEA_API_SECRET! },
  appId:       process.env.ELYSEA_APP_ID!,
  countryCode: 'GB',
  region:      'EU',
});

The region field is mandatory. It sets the brain's EU regions; the code still accepts paths outside the EU possible (direct model access, providers whose region is not set), listed in the privacy policy.

§2 — API surface

identity.resolve()

typescript

const { coreUserId } = await elysea.identity.resolve({
  userJwt: req.headers.authorization, // JWT issued by your auth provider
});
// coreUserId: opaque identifier derived from ELYSEAID
// Never the pseudonym itself — never the underlying identity

pipeline.run()

typescript

const result = await elysea.pipeline.run({
  userInput:           message,
  coreUserId,
  conversationHistory: history,   // Message[] — { role, content }[]
});

// result : PipelineResult
// {
//   response:         string,    // text response
//   posture:          string,    // active Guardian posture
//   guardianAction:   string,    // 'pass'|'warn'|'block'
//   canonConformance: boolean,   // true if compliant with canons
//   errorCode?:       string,    // if guardianAction === 'block'
//   errorMessage?:    string,    // if guardianAction === 'block'
// }

memory.write()

typescript

await elysea.memory.write(
  coreUserId,
  {
    type:       'useful_context',                        // one of 5 authorised types
    content:    'Works in UTC+2, distributed team.',     // ≤ 256 characters
    expires_at: '2027-01-01T00:00:00Z',                  // mandatory TTL
  },
  consentToken, // ELYSÉA consent token (P7 without this token)
  proof,        // builder consent proof — required (see below)
);

guardian.audit()

typescript

// Build the audit result after pipeline.run()
const auditPost = elysea.guardian.buildAuditResult(
  coreUserId,
  result.posture ?? 'present_neutral',
  result.guardianAction,
  null,
);
const { auditId, persisted } = await elysea.guardian.audit(auditPost);
// auditId   → persisted audit identifier
// persisted → true if recorded Core-side

Memory: proven consent required

Effective in the deployed brain: without a proof, the write is refused. The SDK enforces it too: without a proof, nothing is sent.

ELYSÉA writes no memory without a consent proof supplied by you, the builder. The consentToken authenticates the operation (P7); it is not consent.

What you must show — an explicit, separate memory consent text (not buried in terms and conditions), accepted by a positive action of the user.

What you must keep — the exact text shown, its version, the time of consent and the user concerned, so you can prove the consent.

What you must send — with every memory.write, a MemoryConsentProof. Every field is required and non-empty; the SDK never fills one in for you.

Field	Content
`granted`	true
`consent_text_version`	version of the text shown
`libelle_sha256`	libelleSha256(text) — hex SHA-256 of the UTF-8 bytes of the exact text shown, with no normalisation
`consent_granted_at`	ISO 8601 time of consent, recorded by you
`constructor_legal_entity`	your legal entity
`app_id`	your application

typescript

import { libelleSha256, ElyseaSDKError, ElyseaNetworkError, type MemoryConsentProof } from '@elysea/core';

// Your record of the consent (exact text shown, version, time)
const proof: MemoryConsentProof = {
  granted: true,
  consent_text_version: consent.version,
  libelle_sha256: libelleSha256(consent.textShown),
  consent_granted_at: consent.grantedAt,
  constructor_legal_entity: 'Your Company Ltd',
  app_id: 'your-app',
};

try {
  await elysea.memory.write(
    coreUserId,
    { type: 'preferences_communication', content: 'Short answers.', expires_at: '2027-01-01T00:00:00Z' },
    consentToken,
    proof,
  );
} catch (e) {
  if ((e instanceof ElyseaSDKError || e instanceof ElyseaNetworkError) && e.errorCode === 'CONSENT_PROOF_REQUIRED') {
    // Memory disabled for this user: do not retry without a complete proof.
  }
}

Without a proof, memory stays disabled

missing or incomplete proof → ElyseaSDKError CONSENT_PROOF_REQUIRED, before anything is sent;
refusal by the brain (HTTP 403 CONSENT_PROOF_REQUIRED) → ElyseaNetworkError with errorCode 'CONSENT_PROOF_REQUIRED' — never silent, never mistaken for an authentication error.

Withdrawal — as soon as the user withdraws consent, stop sending the proof (no new write is then possible) and erase items already written with memory.delete(coreUserId, itemId, consentToken). The brain does not yet expose an SDK route to withdraw the recorded consent itself.

ELYSEA.ARCH.CANON_GUARDIAN_SDK.v1 — FROZEN

§3 — 8 prohibitions

A third party can TIGHTEN — never weaken.

You can configure ELYSÉA to be stricter than the baseline (block topics, reduce memory types used, require finer consent). You cannot configure ELYSÉA to be less protective. The Guardian SDK rejects any configuration that would weaken an existing prohibition — in the pipeline, not only in a policy.

Block behaviour: the Guardian never returns HTTP 403. It returns a normal pipeline response — guardianAction: “block”, posture: “present_neutral”. The user does not know a bypass attempt occurred. The internal log does.

P1IMMEDIATE BLOCK

Bypass or modify D0

Any attempt to replace, neutralise, or short-circuit the baseline ethical directive (D0). D0 can only be tightened — never weakened.

signal: P1_D0_OVERRIDE_ATTEMPT

P2IMMEDIATE BLOCK

Access raw memory

Direct reading of a user's memory items without going through the consented resolution pipeline. No SDK endpoint exists for this.

signal: P2_MEMORY_RAW_ACCESS

P3IMMEDIATE BLOCK

Safety gate bypass

Any request designed to circumvent safety guardrails (prompt jailbreak, system injection, unsigned external LLM wrapping).

signal: P3_SAFETY_GATE_BYPASS_ATTEMPT

P4IMMEDIATE BLOCK

LLM without compliant wrapper

Direct call to an external LLM without going through runLLMControlled. The builder selects their model within the canonical pipeline — never by bypassing it. Block since v0.4.1.

signal: P4_NON_CONFORM_LLM_SIGNATURE

P5BLOCK

Watermark absent in output

Pipeline response returned without ELYSÉA traceability metadata. The compliance chain is broken.

signal: P5_WATERMARK_MISSING

P6IMMEDIATE BLOCK

Disabling ethical telemetry

Disabling canon compliance telemetry (posture, Guardian log). Enforcement is architectural on the Core side — no API allows disabling it.

signal: P6_TELEMETRY_DISABLED

P7BLOCK

Call without consent token

Pipeline or memory.write request initiated without providing a valid ELYSÉA consent token for the relevant user.

signal: P7_MISSING_CONSENT_TOKEN

P8IMMEDIATE BLOCK

Verified badge without attestation

Displaying 'Verified — public record' or any ELYSÉA certification badge without a valid Core attestation. Block since v0.4.1 — immediate revocation if fraud is confirmed.

signal: P8_UNCERTIFIED_BADGE_USAGE

Source: ELYSEA.ARCH.CANON_GUARDIAN_SDK.v1 §3 — ELYSEA.SDK.INTEGRITY_PROTECTION.v1 §4. This canon is frozen: ELYSÉA does not remove a prohibition by commercial decision.

§4 — Tiers & access

Tier	Price	Key	Environment	Quota	Badge
TEST	Free	`sk_test_`	Sandbox · no time limit · 500 interactions per month	1 app · community	Powered by ELYSÉA
FOR YOUR PRODUCT	€2.50 excl. VAT, then graduated	`sk_live_`	Production · per active user per month	Graduated by bracket: €2.50 / €1.50 / €0.80 excl. VAT	Powered by ELYSÉA
FOR YOUR TEAMS Enterprise · Platforms · Public · Education: on request	€30 excl. VAT / year, then volume-based	`sk_live_`	Production · per covered employee	Annual licence · compliance report included	Powered by ELYSÉA

The brain pipeline requires the builder’s own model key (BYOK); key deposit is not open yet, so the pipeline is not yet open to builders. TEST free: 500 interactions per month. FOR YOUR PRODUCT graduated by bracket from the first active user, no fixed fee, no minimum subscription. Each plan includes 200 messages per active user per month; beyond that, €0.005 excl. VAT per message, billed pro rata. Service suspended after 10 days of non-payment. Sales opening soon. No payment is accepted yet.FOR YOUR TEAMS annual licence per covered employee. Enterprise and special cases on request. Full details: pricing page.

§5 — Trust mark & badges

Test and production

First-level badge. Indicates the app integrates the ELYSÉA SDK with the 8 prohibitions active. Verifiable by the user via their ID portal.

Verified — public record

Measurement on sealed corpora

Awarded after measurement procedure on precise pipeline states — results versioned and published after the campaign. This level is not yet issued (campaign in progress). Process separate from subscription.

Revocation

Immediate revocation

P1, P2, P3 (active bypass attempt) and P8 (confirmed badge fraud). No grace period.

10-day window

P4, P5, P6, P7 — non-fraudulent infractions. The builder receives a notification and has 10 days to correct before revocation.

Appeal — 15 days

Any revocation may be contested within 15 calendar days following the notification. Procedure described in the partner contract.

Source: ELYSEA.SDK.TRUST_MARK.v1 §3, §5. See also: Trust mark page.

trust.verify() — programmatic verification

The trust namespace of the SDK allows verifying the verification status of an app and validating the authenticity of an HMAC attestation Core-side. Typical use: display the correct badge to the user, or audit a third-party partner.

trust.fetchAttestation(appId)

→ Promise<TrustMarkAttestation | null>

Fetches the trust mark attestation from the Core for a given appId. Returns null if the Core is unreachable or the appId is unknown.

trust.getStatus(attestation)

→ CertificationStatus

Derives the verification status from an attestation. Pure function — no network call. Result: 'powered_by' | 'certified_ethical' | 'none'.

trust.verify(attestation)

→ Promise<{ valid: boolean }>

Verifies the HMAC attestationToken with the Core (POST /verify/attestation). The Core validates the signature server-side. Returns { valid: false } on any failure — no exception raised.

typescript

// Verify the trust mark of a partner app
const attestation = await elysea.trust.fetchAttestation('app_a40a8bd4-008c-4ef4-aef7-b9666d6846a8');

if (!attestation) {
  // Unknown app or Core unreachable
  return { certified: false };
}

const status = elysea.trust.getStatus(attestation);
// status → 'powered_by' | 'certified_ethical' | 'none'

const { valid } = await elysea.trust.verify(attestation);
// valid → true if HMAC is confirmed Core-side
// valid → false if token is invalid, expired, or forged

ELYSEA.SDK.SANDBOX_PARTNER.v1 — FROZEN

§6 — Sandbox — 5 invariants

I-SB-1

firm_safety always active

The main safety mode cannot be disabled in sandbox. Any attempt to pass firm_safety: false is silently ignored.

I-SB-2

D0 active without exception

The baseline ethical directive (D0) is active in sandbox exactly as in production. Guardian behaviour is identical.

I-SB-3

Guardian SDK active

All Guardian blocks are functional under sk_test_. Sandbox is a genuine compliance test — not a permissive playground.

I-SB-4

8 prohibitions active

P1 through P8 are fully enforced. Error signals returned are identical to production.

I-SB-5

Rule K applied

Rule K: the user's raw memories (items marked K) do not leave for another application — a data guard, in sandbox as in production. No test endpoint bypasses this rule.

Environment mismatch error

typescript

// An empty or unprefixed key throws ElyseaSDKError synchronously at startup
import { createElyseaClient, ElyseaSDKError } from '@elysea/core';

try {
  const elysea = createElyseaClient({
    baseUrl:     process.env.ELYSEA_BASE_URL!,
    auth: { apiKey: '', apiSecret: 'secret' }, // empty key → sync error
    appId:       'my-app',
    countryCode: 'GB',
    region:      'EU',
  });
} catch (err) {
  if (err instanceof ElyseaSDKError) {
    console.log(err.code);   // 'AUTH_INVALID_KEY'
    console.log(err.action); // recommended action
  }
}

§7 — Error codes

Code	Type	Cause	Recommended action
`AUTH_INVALID_KEY`	Config	Empty key or missing sk_test_/sk_live_ prefix — synchronous error at startup	Check ELYSEA_API_KEY in createElyseaClient({ auth: { apiKey } })
`P1_D0_OVERRIDE_ATTEMPT`	Guardian BLOCK	D0 bypass attempt	P1 violation — architecture review required
`P2_MEMORY_RAW_ACCESS`	Guardian BLOCK	Direct user memory read	Use only the consented resolution pipeline
`P3_SAFETY_GATE_BYPASS_ATTEMPT`	Guardian BLOCK	Safety gate circumvention detected	Full review of prompt and LLM architecture
`P4_NON_CONFORM_LLM_SIGNATURE`	Guardian BLOCK	Direct LLM call without going through the canonical pipeline	Use only the canonical pipeline via pipeline.run()
`P5_WATERMARK_MISSING`	Guardian BLOCK	Pipeline response without traceability metadata	Check integration — do not modify the raw pipeline response
`P6_TELEMETRY_DISABLED`	Guardian BLOCK	Attempt to disable ethical telemetry (posture, Guardian log)	Remove any telemetry-disabling flag — enforcement is architectural
`CONSENT_PROOF_REQUIRED`	Memory	memory.write without a complete builder consent proof — thrown before sending, or HTTP 403 from the brain; no memory written	Send a complete MemoryConsentProof — see "Memory: proven consent required"
`P7_MISSING_CONSENT_TOKEN`	Guardian BLOCK	Call without valid ELYSÉA consent token	Collect user consent before any call
`P8_UNCERTIFIED_BADGE_USAGE`	Guardian BLOCK	'Verified — public record' badge displayed without valid Core attestation	Remove the badge or obtain an attestation via official ELYSÉA audit

Guardian blocks do not generate HTTP 4xx. The response is always a valid PipelineResult with guardianAction: “block” and posture: “present_neutral”.

A compliance question? An undocumented edge case?

Write to the founder Download docs (PDF)Quickstart

The SDK technical reference.Everything you need to integrate, nothing more.