Home → Architecture → APIs

APIs

Ironmark is a web application backed by a versioned REST API, and the web interface is one client of that application layer. A substantial API surface supports automation, headless publishing, ingest, export, and integration; this page does not claim one-to-one API coverage for every interface action.

Surface

• Versioned — /api/v1/. Breaking changes bump the version; additive changes land in place.
• OpenAPI — the running server publishes its own OpenAPI document. Generated clients stay honest.
• JSON in / JSON out — except where the content is a file (XML source, IADS package, PDF, graphic).

Auth

Two paths into the API:

• Session cookie — same auth the browser UI uses. Suitable for interactive tools that log the user in.
• API tokens — per-user, self-issued from the user's profile page. Scope is HTTP-method-based (api_readonly permits any GET; api_full permits any method). The token then acts as its owning user — the user's role and project membership limit what any call resolves to. Revocable. Recommended for scripts, CI, and integration jobs so a script's blast radius matches a real user.

Tokens don't broaden access. A token issued by an author who can reach projects A and B can hit A and B; nothing else.

PAT controls

• Prefix — every personal access token starts with iak_ so credentials-in-logs scanners can identify them at a glance.
• Non-admin expiry cap — user-issued PATs are capped to a short maximum expiry. Long-lived tokens require admin issuance so the audit path is explicit.
• Admin kill switch — admins can disable all user-issued PATs instance-wide with a single toggle in the admin panel. Immediate revocation for the whole instance.

Notification surface

Notifications fire on document state changes, review transitions, publish completion, and audit events. Delivery paths:

• Email — per-user preferences (see workflow/review).
• Pull — integrations can poll the supported resource and audit endpoints available to their token. Ironmark does not push general webhook events to third-party endpoints on its own.

Common integration shapes

Scheduled publish from CI

A CI job holds a scoped API token. On a schedule, it calls the publish endpoint, waits on the job to complete, downloads the artifact, and deposits it in the delivery share. Ironmark's audit log records the CI user's action as it would any human's.

Asset-registry sync

Programs that maintain their asset registry (serials, tail numbers, MDS) in an external system push into Ironmark's PCT via API. Applicability preview picks the new asset up on the next filter.

Ingest from an external LSA system

The GEIA-STD-0007 ingest flow (workflow/applicability) can be driven from the API. External LSA cuts a baseline → posts to Ironmark → the master project preview shows dispositions → CI or a human commits.

Related

← Back to Architecture