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 — no AI-generated content.

Quickstart Download docs (PDF)SDK & Pricing

§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). Mixing sk_test_ in production or sk_live_ in sandbox immediately raises ELYSEA_INIT_ERROR.

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. ELYSÉA operates exclusively in the EU — no fallback to non-EU regions is available.

§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:     'context',         // one of 5 authorised types (FROZEN)
  content:  'Works in UTC+2, distributed team.',  // ≤ 256 characters
  ttlDays:  90,                // TTL mandatory — no infinite persistence
  scope:    'your-app-id',     // scoped to your app only
});
// Requires the user's active scoped consent (P7 otherwise)

guardian.audit()

typescript

const log = await elysea.guardian.audit({
  coreUserId,
  event: 'session_close',
});
// Returns the GuardianLog for the session
// Useful for compliance and debugging — read only

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 — by architecture, not by 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

P4WARN

LLM without valid signature

Pipeline call towards an LLM model not presenting a valid ELYSÉA watermark. Logged — escalated if recurring.

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

Cross-builder memory without consent

Exploitation of memory data from another ecosystem app without the user's active scoped consent.

signal: P6_CROSS_BUILDER_CONSENT_MISSING

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

P8WARN → REVOCATION

Unverified badge displayed

Display of an ELYSÉA trust mark (Powered by / Verified — public record) without active validation. Warning first — 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 cannot remove a prohibition by commercial decision.

§4 — Tiers & access

Tier	Price	Key	Environment	Quota	Badge
TEST	Free	`sk_test_`	Sandbox · no time limit · volume capped	1 app · community	Powered by ELYSÉA
FOR YOUR PRODUCT	From €2.50	`sk_live_`	Production · per active user per month	Volume discount: €2.50 / €1.50 / €0.80	Powered by ELYSÉA
FOR YOUR TEAMS Enterprise · Platforms · Public · Education: on request	From €30/year	`sk_live_`	Production · per covered employee	Annual licence · compliance report included	Powered by ELYSÉA

BYOK required — LLM tokens are always the builder's responsibility. TEST free with no time limit. FOR YOUR PRODUCT volume-discounted from the first active user. FOR YOUR TEAMS annual licence per covered employee. Enterprise and special cases on request. Full details: pricing page.

§5 — Trust mark & badges

Discovery and above

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

Guarantee K intact

The user's sacred memory (items marked K) is inaccessible in sandbox as in production. No test endpoint bypasses this rule.

Environment mismatch error

typescript

// Error if sk_test_ key used in production (or vice versa)
// Verify ELYSEA_API_KEY matches the target environment

try {
  const elysea = createElyseaClient({
    baseUrl:     'https://core.elysea.eu',
    auth: { apiKey: 'sk_test_abc123', apiSecret: 'secret' },
    appId:       'my-app',
    countryCode: 'GB',
    region:      'EU',
  });
} catch (err) {
  // err.code === 'ELYSEA_INIT_ERROR'
}

§7 — Error codes

Code	Type	Cause	Recommended action
`ELYSEA_INIT_ERROR`	Config	Invalid init parameters (baseUrl, auth, appId…)	Check createElyseaClient({ baseUrl, auth, appId, countryCode }) config
`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 WARN	LLM without ELYSÉA watermark	Use only ELYSÉA-approved models
`P5_WATERMARK_MISSING`	Guardian BLOCK	Pipeline response without traceability metadata	Check integration — do not modify the raw pipeline response
`P6_CROSS_BUILDER_CONSENT_MISSING`	Guardian BLOCK	Cross-app memory crossing without scoped consent	Verify the active cross-app consent token
`P7_MISSING_CONSENT_TOKEN`	Guardian BLOCK	Call without valid ELYSÉA consent token	Collect user consent before any call
`P8_UNCERTIFIED_BADGE_USAGE`	Guardian WARN	Badge displayed without active validation	Remove the badge

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?

Talk to the team Download docs (PDF)Quickstart

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