Skip to Content
Getting StartedProduction Ready

Production Ready

Use this checklist before moving an integration from local testing to production traffic.

Create API keys

Create keys from Settings > API Keys in the tenant dashboard. Use a dedicated key per service, worker, or customer-owned integration so audit logs can identify the caller.

  • Name the key after the service that will use it.
  • Store the secret in a secret manager, not in source control or chat.
  • Keep separate keys for development, staging, and production tenants.

Required scopes

Grant only the scopes the integration needs. Public API routes reject missing scopes with 403.

Common starting points:

ScopeUse it for
reports:readDashboards, report runs, and summary endpoints.
reports:writeQueueing report builds and exports.
audit:readTenant audit logs and webhook delivery diagnostics.
controls:readControl status, framework mappings, and test health.
controls:writeRecording control test results.
evidence:readListing evidence and evidence sources.
evidence:writeUploading evidence or creating evidence source records.
files:readReading uploaded file metadata.
files:writeRequesting uploads or attaching files.
webhooks:readReading webhook subscriptions and delivery attempts.
webhooks:writeCreating, rotating, disabling, or testing webhooks.

Install SDKs

Use the official SDK for your runtime and pin versions in your lockfile.

pnpm add @asiri-ng/sdk-ts
pip install asiri-sdk

TypeScript:

import { createAsiriClient } from '@asiri-ng/sdk-ts';
 
const asiri = createAsiriClient({
  baseUrl: 'https://api.asiri.ng',
  apiKey: process.env.ASIRI_API_KEY,
});

Python:

import os
 
from asiri import AsiriClient
 
asiri = AsiriClient(
    base_url="https://api.asiri.ng",
    api_key=os.environ["ASIRI_API_KEY"],
)

Retry and idempotency

Retry transient 429 and 5xx responses with exponential backoff. For mutating requests, pass a stable Idempotency-Key header so a retry cannot create duplicate work.

await asiri.POST('/v1/reports/build', {
  body: { type: 'audit_summary', format: 'json' },
  headers: { 'Idempotency-Key': requestId },
});

Webhook signing

Verify every incoming webhook before processing it.

  • Store the webhook signing secret in your secret manager.
  • Validate the signature header and reject mismatches.
  • Branch on event_type and event_version before parsing data.
  • Keep pinned event versions until your handler is upgraded.

Rotation and revocation

Rotate keys and webhook secrets with overlap windows.

  1. Create a replacement key or secret.
  2. Deploy the new value.
  3. Confirm traffic succeeds with the replacement.
  4. Revoke the old value.
  5. Review the audit log for unexpected callers.

Revocation is immediate. Treat pasted or exposed secrets as compromised and rotate them.

Error handling

Every API error returns a JSON envelope with a machine-readable code, message, optional details, and request id.

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid",
    "requestId": "req_123"
  }
}

Log requestId, status code, route, and integration name. Do not log API keys, webhook secrets, or raw evidence payloads.

Evidence automation boundary

If your integration sends evidence into Asiri, keep the source artifact traceable. Include a stable source id, collection timestamp, control mapping, and raw payload hash when available. Asiri can preserve evidence, freshness, workflow, and audit-trail metadata, but a qualified owner still reviews high-risk outputs before they are used for buyer commitments, regulator-facing submissions, or auditor reliance.

For native connector collection, see Concepts → Evidence Automation.

AuthenticationQuickstart