# Sovereign Foundry — Partner Integration Guide

Public interface handout • v1 • reviewed 10/08/2026

- Human reference: https://sovereignautoengine.com/developers
- OpenAPI 3.0.3 JSON: https://sovereignautoengine.com/foundry/openapi.json
- Partner questionnaire: https://sovereignautoengine.com/connect
- Base API: https://sovereignautoengine.com/api/public/v1

This is public interface information, not access permission or a production-readiness certification. It does not disclose filed rating algorithms, proprietary loss models, secrets, database schemas or operational data. Download the JSON and import it into Postman or Swagger tooling. Response objects delegated to existing engines are explicitly marked partial/variable; validate the agreed shape in the approved sandbox before generating a production client.

## 1. Integration directions and responsibilities

**Apps calling Sovereign:** Mobile/insured portals, raters and custom applications consume the Sovereign contracts. Their trusted server holds a licensee-scoped API key and authorizes each end user before returning any policy data.

**Sovereign calling a provider:** Verisk, TransUnion, Fenris and payment processors generally define their own interfaces. Supply their current API documentation, account/subscriber requirements, permitted use, consent obligations, report codes, underwriting checkpoints, sandbox and error contracts. Sovereign commissions an adapter using the approved licensee-specific account. A vendor catalog listing is not an implemented adapter.

**Bidirectional:** Agree both contracts, identifiers, authority over each field and reconciliation. Telematics ingestion does not itself authorize changing a filed premium or an in-force policy.

Sovereign supplies existing contracts and approved access. The partner supplies application/server architecture, identity controls, mappings and webhook receivers. Both agree privacy terms, consent, retention, volumes, support, change notices, SLA and acceptance criteria. None of those commercial guarantees are implied by this handout.

## 2. Capability matrix — current implementation

| Capability | Status | Contract / limitation |
|---|---|---|
| Policy list | Available, licensee-wide | GET /policies; limit defaults to 50, cap 200; no cursor |
| Policy, drivers, vehicles | Available | GET /policies/{id}; UUID lookup, partly masked profile |
| Billing | Available | GET /policies/{id}/billing; latest term, charges, schedule, paid_cents, balance_cents, next_due |
| Documents | Metadata only | GET /policies/{id}/documents; up to 100 IDs/titles/kinds/dates; no download/share URL |
| Quote/application/signature sequence | Existing workflow | Documented checkout contracts; exercise in approved sandbox |
| Bind | Sandbox only | Production returns 403 payment_verification_required |
| General policy payment / refund / autopay | Not a public v1 contract | No payments/submit route; processor verification and server-calculated intent needed |
| Insured login / account linking | Separate contract required | API keys do not authenticate an insured |
| FNOL / claim status | Separate contract required | No public claims/fnol or claim-status endpoint |
| Document sharing | Separate contract required | Must use approved expiring insured links, not raw artifacts |
| Trip data, drive scores, underwriting reports | Provider adapter / contract required | No v1 telematics/report-ingestion endpoint |
| Endorsements / cancellation / renewal servicing | Separate contract required | No public servicing mutations in this documented surface |

Earlier illustrative endpoint suggestions are not implementation commitments. Do not build against routes absent from the OpenAPI document.

## 3. Authentication and tenancy

Use HTTPS and JSON. Supply either:

```http
Authorization: Bearer <issued-server-side-key>
```

or `x-api-key: <issued-server-side-key>`.

Keys start `sae_test_` or `sae_live_`, are stored hash-only, and are shown once at issuance. Scopes are `quote`, `bind`, `read`. Identity/licensee/environment come from the validated key, never a submitted licensee ID. Revoked, disabled and expired keys are rejected; inactive licensees cannot use the API.

Keys stay on trusted servers, never in mobile binaries, browser bundles or public repositories. Rotate through the approved administrator process. Use separate approved keys by partner/environment and least privilege.

**Important consumer boundary:** A read key can list the licensee’s policies; it is not an insured session. Agree server-enforced ownership linking, MFA/recovery/consent, logout and revocation before exposing real records to an app. Policy number plus ZIP or DOB alone is not a sufficient production identity design. No insured-login endpoint is promised here.

**Sandbox:** The environment tag is not a separate database and does not itself guarantee synthetic data. Obtain a dedicated approved sandbox licensee and synthetic fixtures. Outbound communications/webhooks are held while that licensee is in Test mode. Sandbox intake does not automatically provision accounts or keys.

## 4. Data conventions and system of record

- Money uses integer cents in `_cents` response fields. The rating input `acv` is vehicle value in dollars, as specified in OpenAPI; do not treat it as cents.
- API dates are ISO `YYYY-MM-DD`; timestamps are UTC ISO timestamps. Display dates as `MM/DD/YYYY`.
- Names are separate first/last input fields. Phones display `(XXX) XXX-XXXX`.
- Sovereign computes authoritative premium, charges, schedules, amount due and cash application. Partners do not send arbitrary amounts or infer cancellation cure from balance alone.
- Premium and cash are separate ledgers. Pay-plan/processor settings never change filed premium. Published filings and in-force version pins stay immutable.
- Custom apps never write core tables directly. Operational mutations go through the validating core contract.
- Masked driver/vehicle fields are display data, not identity verification material. Agree each necessary field and its purpose; do not request full personal data by default.

## 5. Endpoint sequence

The downloadable OpenAPI lists fields, methods, scopes and known response shapes.

1. `POST /sessions` (quote scope): optional agency_id, resolved inside the key’s licensee. Returns session_id, environment and filed constraints effective today.
2. `POST /quotes` (quote): session_id and rating answers. Returns quote_id, quote_number, session-bound bind_token and six/twelve term results; a decline is HTTP 200 with `ok:false`, `declined:true`, reasons.
3. `POST /quotes/term` (quote): session_id, bind_token, term_months (6 or 12).
4. `POST /applications` (quote): credentials, quote_id, term_months, payment_plan_code.
5. `POST /applications/{id}`: read a session-owned application using checkout credentials; no additional scope is checked on this action.
6. `POST /applications/{id}/update` (quote): credentials plus applicant/address/driver/vehicle patch.
7. `POST /applications/{id}/attestations` (bind): credentials and accepted_codes.
8. `POST /applications/{id}/signature-step` (bind): credentials, inline boolean; follows the carrier’s form/signing gates.
9. `POST /applications/{id}/amount-due`: credentials; no additional scope is checked on this action. Returns variable core amount-due output, not a general payment endpoint.
10. `POST /applications/{id}/bind` (bind): sandbox only; credentials, method card/ach, receipt/reference. Production is explicitly blocked until verified payment integration exists.

Do not mistake API authentication for payment confirmation. Never send PAN, CVV, bank numbers or processor secrets. A future payment contract must use hosted checkout or approved tokenization, core-calculated amounts and verified, idempotent processor events.

Example, substituting an issued sandbox key on your server:

```sh
curl -X POST https://sovereignautoengine.com/api/public/v1/sessions \
  -H 'Authorization: Bearer <issued-sandbox-key>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

Read `/whoami` to confirm licensee/environment/scopes. `/health` is an unauthenticated liveness probe. Policy reads use policy UUIDs, not policy numbers. Billing `balance_cents` is open charge balance; `next_due` is a grouped schedule line or null, not a coverage guarantee or processor intent.

## 6. Errors, retry and concurrency

```json
{ "error": { "code": "insufficient_scope", "message": "This key does not carry the required scope." }, "request_id": "req_example" }
```

The error envelope is not RFC 7807. HTTP 400 is invalid input/engine rejection; 401 invalid or expired key; 403 insufficient scope/inactive account/production-bind restriction; 404 unknown or outside-licensee record; 409 no applicable filing; 429 limiter; transient 5xx service failure. Inspect business `ok`/`declined` even after HTTP 200.

The existing limiter is best-effort 120 requests per minute per key per running instance, not a globally enforced quota. No Retry-After guarantee is asserted. Agree volume and service windows separately.

Use bounded exponential backoff with jitter on 429/transient errors. **Generic Idempotency-Key is not implemented.** A timeout may follow a successful write: reconcile before retrying a POST, rather than blindly replaying and creating duplicates. Agree mutation concurrency/idempotency contracts for future partner actions.

Keep request_id/x-request-id and non-PII status codes for support; do not log bodies, keys, personal identifiers or webhook secrets.

## 7. Signed webhooks

Configure an approved HTTPS endpoint per licensee/environment. Events supported by the event catalog: `quote.created`, `application.attested`, `signature.completed`, `policy.bound`, `policy.cancelled`, `payment.posted`, `claim.opened`. Agree which firing points and payload fields apply to the integration; `claim.opened` is not a public FNOL endpoint and does not imply claim-status updates.

Headers:

- `x-sovereign-timestamp`: Unix seconds.
- `x-sovereign-signature`: `v1=<hex HMAC-SHA256>`.
- Signed input: timestamp + literal period + **original raw body bytes**.

```json
{ "event": "policy.bound", "created_at": "2026-10-08T12:00:00.000Z", "data": { "policy_id": "synthetic-policy-id" } }
```

The example illustrates the envelope, not a guarantee of event-specific fields. Validate and agree those fields in the sandbox. Never verify parsed/re-serialized JSON. Reject absent signatures; compare in constant time. A five-minute receiver replay window is recommended, with synchronized clocks. Persist/deduplicate durably before acknowledging 2xx.

Receiver example (Node.js partner server, not mobile code):

```js
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyWebhook(rawBody, timestamp, signature, secret) {
  if (!/^\d+$/.test(timestamp ?? '') || !/^v1=[a-f0-9]{64}$/.test(signature ?? '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', secret).update(timestamp + '.').update(rawBody).digest();
  const presented = Buffer.from(signature.slice(3), 'hex');
  return presented.length === expected.length && timingSafeEqual(expected, presented);
}
```

Failed deliveries retry through the nightly cycle, up to five attempts. Test-mode traffic is held. Order is not guaranteed. There is no global event_id in the envelope; agree a business-key/event/time deduplication strategy and reconciliation reads. Do not assume exactly-once delivery or a real-time delivery SLA. Keep the receiver’s secret private and arrange rotation.

## 8. Partner questionnaire and kickoff decisions

Submit https://sovereignautoengine.com/connect. The private profile asks:

1. Company, website, separate first/last technical contact, email/phone.
2. Integration category and requested capabilities.
3. Audience, licensee relationship, account linking and authorization.
4. Application/server hosting, regions and inbound/outbound directions.
5. Fields/actions, timing, volumes, underwriting checkpoints, provider docs.
6. Webhooks, synchronization, retries, duplicates and reconciliation.
7. Processor/hosted/tokenized handoff, fees, failures and receipts.
8. Encryption, consent, privacy, retention/deletion, incident response and assessments.
9. Sandbox fixtures, acceptance criteria, support ownership and timeline.

This produces requirements for a partner-specific agreed profile; it does not automatically generate a final contract, provision an account or grant access. Never include credentials, card data, real insured records or confidential attachments. Platform staff review profiles privately; contact growth@sovereignautoengine.com for a profile deletion request.

## 9. Acceptance and production gate

Agree a field-by-field mapping and current/needed capability matrix first. Synthetic sandbox cases should include active, pending-cancellation, cancelled/lapsed, multi-driver/vehicle and no-document policies where provisioned. Test missing/expired/revoked keys, insufficient scopes, cross-licensee record IDs, cross-insured authorization, invalid input, declines, ambiguous POST responses, duplicate/out-of-order webhooks, stale signatures, payment failures and reconciliation.

Independent human/owned-script security acceptance is required, especially cross-licensee/cross-insured access. Sovereign’s platform certification checks sandbox traffic, quote and bind completion, webhook subscription and an effective filing. **Certification never bypasses the production bind block.** Processor verification, consumer identity, missing partner contracts, commercial/privacy approval and operational support must be resolved before live use.

This guide cannot cover every provider or future operation. Record unsupported requirements explicitly; do not infer them from similar platforms or proposed endpoint names.
## AI assistants (MCP)

Licensee staff can connect MCP-compatible AI assistants at `/mcp`. Phase 1 is read-only, uses OAuth so each caller acts as their own Sovereign user under their role, masks names and contact details, and logs every call. It is off by default and requires the platform, the licensee admin and a per-user grant. It is not a partner integration channel: there are no write tools, no free-form queries and no API-key access. Use the REST API in this guide for applications.