Subscriber API Access

The production 7DEA Subscriber API lets a paid, authorized account connect AEGIS, the account's entitled lenses, and authorized tools to software, Postman, automation platforms, SDKs, and AI agents. The API never expands the authority of the issuing user: the user, organization membership, subscription, API key, requested scope, and current plan entitlement must all remain active.

Production availability as of July 20, 2026

The production release includes customer-managed API keys, copy-once secret display, Bearer authentication, GET /capabilities, AEGIS responses, entitled lens discovery, authorized-tool discovery, usage state, rotation, and revocation.

The public catalog contains 19 production lenses, but a subscription authorizes only its plan-specific subset. The current Growth entitlement returns three core scopes (aegis:respond, lenses:read, and tools:read), 13 entitled lenses, and two authorized tools. Pilot and Enterprise access may differ. Always treat the authenticated GET /capabilities response as the controlling runtime record for the key.

Durable jobs and signed webhooks are documented below as a controlled-preview contract for integration planning. They are not currently active production capabilities for self-serve Pilot or Growth subscriptions. The permanent production worker is disabled, and job or webhook requests without a separately authorized Enterprise activation may return 403. Do not design a production dependency around those preview operations until /capabilities explicitly returns the required run or webhook scopes and AIMQWEST confirms activation in the applicable Enterprise order form.

Environment and host selection

Choose one lane and keep its frontend, backend, credentials, and data together.

| Purpose | Application | API base URL | Stripe mode | | --- | --- | --- | --- | | Development | https://dev.7dea.ai | https://api-dev.7dea.ai/v1 | Test | | Release-candidate qualification | https://app-green.7dea.ai | https://api-green.7dea.ai/v1 | Test | | Production | https://app.7dea.ai | https://api.7dea.ai/v1 | Live |

staging.7dea.ai and dev-api.7dea.ai are not active canonical endpoints. Never send a DEV or Green key to the production API, or a production key to a non-production API.

The machine-readable contract for each lane is available at:

DEV: https://api-dev.7dea.ai/v1/openapi.json
Green: https://api-green.7dea.ai/v1/openapi.json
Production after V3 release: https://api.7dea.ai/v1/openapi.json

Prerequisites

Before creating a key:

Sign in to the matching 7DEA application.
Confirm that the account has an active paid subscription.
Confirm active membership in the organization that will own the integration.
Decide which scopes the integration actually needs.
Prepare a secrets manager. Do not store the key in source code, screenshots,

chat, tickets, logs, browser bookmarks, or shared documents.

A real subscriber does not run an administrative script to obtain API access. The customer workflow is entirely in the application:

Open Account.
Select API Access.
Choose the organization.
Name the integration.
Select the least scopes required.
Select Create API key.
Copy the secret during its one-time display.
Store it in the integration's secrets manager.
Return to Account → API Access to review usage, rotate, or revoke it.

Authentication

Store the copy-once value in an environment variable:

export SEVENDEA_API_KEY="<copy-once key>"
export SEVENDEA_API_BASE_URL="https://api-green.7dea.ai/v1"

Send it as a Bearer token and include a bounded correlation identifier:

curl "$SEVENDEA_API_BASE_URL/capabilities" \
  -H "Authorization: Bearer $SEVENDEA_API_KEY" \
  -H "X-Correlation-ID: my-integration-capabilities-001"

Do not place the key in a query string. Treat a 401 not_authenticated response as a credential failure: stop, verify the selected environment, and rotate or revoke the key if exposure is possible.

Scopes

Scopes constrain what a key may request. Plan and organization entitlements may constrain it further.

| Scope | Purpose | | --- | --- | | aegis:respond | Request governed AEGIS responses | | lenses:read | List all lenses currently authorized for the subscription | | tools:read | List tools currently authorized for the subscription | | runs:read | Read governed runs and durable-job state | | runs:write | Submit, cancel, or retry authorized durable work | | webhooks:read | Read webhook endpoints and sanitized delivery history | | webhooks:write | Create, rotate, test, disable, enable, or revoke webhooks |

Pilot and Growth currently include the core AEGIS, lens, and tool scopes. Growth does not currently include the run or webhook scopes. Enterprise scopes are explicitly assigned to the organization and require separate activation for controlled-preview operations. Always read /capabilities after authentication instead of assuming that a scope or lens is available.

Discover effective capabilities

GET /capabilities is the deterministic configuration entry point for humans and AI agents. Read it before calling other endpoints.

curl "$SEVENDEA_API_BASE_URL/capabilities" \
  -H "Authorization: Bearer $SEVENDEA_API_KEY" \
  -H "X-Correlation-ID: capabilities-001"

The response identifies the effective plan, scopes, lenses, tools, and contract version. An AI agent should cache only non-secret capability metadata and refresh it at startup, after a 403, after a plan change, or after key rotation.

Generally available discovery endpoints:

GET /capabilities
GET /lenses
GET /tools

Controlled-preview endpoints, available only when /capabilities expressly authorizes them:

GET /jobs
GET /webhooks

The public 7DEA V3 catalog currently contains 19 production lenses. An authenticated GET /lenses response returns the subset entitled to that key; do not assume that every plan receives all 19 lenses.

Request an AEGIS response

Send a unique idempotency key for consequential POST requests:

curl "$SEVENDEA_API_BASE_URL/aegis/respond" \
  -X POST \
  -H "Authorization: Bearer $SEVENDEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: aegis-review-001" \
  -H "Idempotency-Key: aegis-review-001" \
  -d '{
    "user_message": "Identify the governance questions that require human review.",
    "user_state": "subscribed_active",
    "mode_hint": "decision_scoping",
    "current_page": "/account/api-access",
    "selected_lenses": []
  }'

The response includes a mode, message, next actions, warnings, citations, handoff state, and generation path. A response is decision support, not legal advice, certification, or a substitute for accountable human review.

Controlled preview: submit and monitor a durable job

This section is an integration reference, not a promise that durable jobs are enabled for the current subscription. Before submitting work, confirm that GET /capabilities returns runs:write and that the applicable Enterprise order form confirms production-worker activation. Self-serve Pilot and Growth subscriptions do not currently receive this capability.

Durable work is submitted with POST /jobs. The idempotency key represents the logical operation and must remain stable across safe retries.

curl "$SEVENDEA_API_BASE_URL/jobs" \
  -X POST \
  -H "Authorization: Bearer $SEVENDEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: governance-job-001" \
  -H "Idempotency-Key: governance-job-001" \
  -d '{
    "operation": "aegis.respond",
    "input": {
      "user_message": "Prepare a bounded governance scoping response.",
      "user_state": "subscribed_active",
      "current_page": "/account/api-access"
    },
    "source_snapshot": {
      "source": "customer-application",
      "captured_at": "2026-07-20T00:00:00Z"
    },
    "max_attempts": 3,
    "retention_hours": 168
  }'

The service returns 202 and a job identifier. Poll:

GET /jobs/{job_id} for lifecycle state.
GET /jobs/{job_id}/result after SUCCEEDED.
POST /jobs/{job_id}/cancel for best-effort cancellation.
POST /jobs/{job_id}/retry only when the returned state permits retry.

Exact idempotent replay returns the original result. Reusing the same idempotency key for different input returns 409 idempotency_key_conflict. Do not create a new key merely because a request timed out; first replay the same logical request with the same idempotency key.

Controlled preview: configure signed webhooks

This section is an integration reference, not a promise that signed webhooks are enabled for the current subscription. Before configuring a destination, confirm that GET /capabilities returns the required webhook scope and that the applicable Enterprise order form confirms activation. Self-serve Pilot and Growth subscriptions do not currently receive this capability.

Webhook destinations must be public HTTPS endpoints. Private, loopback, link-local, unsafe redirect, and otherwise prohibited destinations are rejected.

Create an endpoint:

curl "$SEVENDEA_API_BASE_URL/webhooks" \
  -X POST \
  -H "Authorization: Bearer $SEVENDEA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: webhook-create-001" \
  -d '{
    "name": "Governance event receiver",
    "url": "https://receiver.example.com/7dea/events",
    "event_classes": ["job.succeeded", "job.failed"],
    "expires_in_days": 90
  }'

The webhook signing secret is shown once. Store it separately from the API key. For every delivery, verify the signature over the exact raw request bytes before parsing JSON. Validate the signature version, timestamp, delivery identifier, and HMAC-SHA256 digest; reject stale timestamps and deduplicate using the delivery identifier.

Receiver behavior:

Read the exact raw body.
Parse the 7DEA signature header into version, timestamp, delivery ID, and

digest components.

Reject an unsupported signature version.
Reject a timestamp outside the receiver's allowed clock-skew window.
Compute HMAC-SHA256 with the stored webhook secret and compare it using a

constant-time comparison.

Reject a delivery ID already processed.
Parse and validate the JSON event only after signature acceptance.
Commit the business transaction and delivery ID atomically.
Return a 2xx response only after durable acceptance.

7DEA treats only 2xx as acknowledgement. Retryable statuses include 408, 425, 429, and server errors. Retry-After is honored within the bounded delivery policy. Other client errors are classified as permanent. Use the API to inspect sanitized delivery history, rotate the secret, test the receiver, disable or enable delivery, or revoke the endpoint.

Rate-limit and usage headers

Inspect these response headers when present:

RateLimit-Limit
RateLimit-Remaining
RateLimit-Reset
Retry-After
usage allowance, consumed, reserved, and remaining headers defined by the

current contract

On 429, stop sending new work until Retry-After or RateLimit-Reset. Use bounded exponential backoff with jitter. Do not retry a non-idempotent POST without its original idempotency key.

Errors and compatibility

Machine-readable errors include:

{
  "error": {
    "code": "machine_readable_code",
    "message": "Human-readable summary",
    "correlation_id": "request-correlation-id",
    "docs": "https://7dea.ai/docs#api-errors"
  }
}

Typical handling:

401: missing, malformed, unknown, expired, or revoked key.
403: authenticated identity lacks current membership, subscription, scope,

or plan entitlement.

404: resource is absent or intentionally concealed across a tenant boundary.
409: idempotency conflict or lifecycle state conflict.
422: request does not match the contract.
429: rate or usage limit reached.
5xx: transient service failure; retry only when the operation is safe and

idempotency is preserved.

Version 1 permits additive compatible changes. Breaking changes require a new major API namespace. Generate clients from the lane's current OpenAPI document and review diffs before upgrading production integrations.

Deterministic AI-agent configuration

An AI agent configuring itself should follow this sequence:

Receive the API base URL and key through a secure runtime secret injection.
Reject any base URL not on the operator-approved environment allowlist.
Call GET /capabilities.
Intersect the requested operation with the returned effective scopes, lenses,

and tools.

Load the current /openapi.json and select the named operation ID.
Generate a bounded X-Correlation-ID.
Generate or retrieve a stable idempotency key for each consequential logical

operation.

Validate every response against the contract.
Honor rate, usage, retry, and terminal-state semantics.
Stop and request human direction on entitlement changes, ambiguous tenant

context, irreversible action, or repeated authorization failure.

Never reveal credentials in model context, logs, traces, screenshots, or

generated documents.

Rotation, revocation, and incident response

Rotate a key when changing custody or on the organization's normal schedule. Revoke immediately after suspected exposure, user separation, organization membership removal, or integration retirement.

After revocation:

Confirm the key is marked REVOKED in Account → API Access.
Confirm a request using the revoked key returns 401.
Remove the old value from every secrets manager and runtime.
Review the displayed last-used timestamp and relevant audit records.
Create a replacement with the minimum scopes only if continued access is

authorized.

Never commit a key or webhook secret. If one enters version control, revoke it immediately; deleting the line from a later commit is not sufficient.

Troubleshooting checklist

When configuration fails:

Confirm the frontend and API belong to the same environment.
Confirm the base URL includes /v1.
Confirm the Authorization header uses Bearer, not Basic auth.
Call /capabilities and compare effective scopes with the intended operation.
Confirm the user, subscription, organization, membership, key, and webhook

endpoint are active.

Confirm system clocks are synchronized for signed webhook verification.
Preserve the correlation ID, HTTP status, error code, and safe timestamp.
Revoke the key if exposure is possible.
Contact 7DEA support with the safe diagnostic packet. Never include the API

key, webhook secret, raw protected payload, payment data, or personal data.