IronID Documentation

The IronID API is a JSON REST API. Base URL: https://api.iron-id.io

Authentication

All authenticated requests require an Authorization: Bearer header with your API key. Generate your keys from the dashboard under API Keys.

bash

curl https://api.iron-id.io/v1/keys \
  -H "Authorization: Bearer YOUR_API_KEY"

Certifications

POST/v1/certify

Submit a file for C2PA certification. Returns 202 Accepted immediately.

bash

curl -X POST https://api.iron-id.io/v1/certify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  -F 'metadata={"author":"Jane Doe","location":"Paris"}' \
  -F "webhook_url=https://myapp.com/webhooks/ironid"

json

{
  "id": "cert_01j8x9abc",
  "status": "pending",
  "certified_url": null,
  "created_at": "2026-04-28T10:00:00Z"
}

GET/v1/certify/{id}

Get the status of a certification. Statuses: pending → processing → certified | failed.

bash

curl https://api.iron-id.io/v1/certify/cert_01j8x9abc \
  -H "Authorization: Bearer YOUR_API_KEY"

json

{
  "id": "cert_01j8x9abc",
  "status": "certified",
  "certified_url": "https://cdn.iron-id.io/certified/...",
  "verification_url": "https://www.iron-id.io/verify/...",
  "c2pa_manifest": { ... },
  "metadata": { "author": "Jane Doe", "location": "Paris" },
  "created_at": "2026-04-28T10:00:00Z"
}

GET/v1/certifications

List certifications (paginated). Parameters: page, page_size, status_filter.

bash

curl "https://api.iron-id.io/v1/certifications?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Verification

Verification endpoints are public — no API key required.

POST/v1/verify

Verify a file by upload. The SHA-256 is computed server-side.

bash

curl -X POST https://api.iron-id.io/v1/verify \
  -F "file=@photo.jpg"

GET/v1/verify/{fingerprint}

Look up a certification by its SHA-256 hash.

bash

curl https://api.iron-id.io/v1/verify/<file-fingerprint>

json

{
  "is_certified": true,
  "certification_id": "cert_01j8x9abc",
  "certified_url": "https://cdn.iron-id.io/certified/...",
  "certified_at": "2026-04-28T10:05:00Z",
  "c2pa_manifest": { ... }
}

API Keys

POST/v1/keys

Create a new API key. The raw key is only returned once.

bash

curl -X POST https://api.iron-id.io/v1/keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Production key","environment":"production"}'

json

{
  "id": "key_abc123",
  "name": "Production key",
  "key_prefix": "sk_prod_Ab1c",
  "raw_key": "sk_prod_Ab1cDe2f...",
  "is_active": true,
  "created_at": "2026-04-28T10:00:00Z"
}

GET/v1/keys

List all user keys.

DELETE/v1/keys/{id}

Revoke an API key.

Webhooks

IronID sends HTTP POST requests to your URL when a certification changes status.

json

{
  "event": "certification.completed",
  "certification_id": "cert_01j8x9abc",
  "status": "certified",
  "certified_url": "https://cdn.iron-id.io/certified/...",
  "verification_url": "https://www.iron-id.io/verify/...",
  "timestamp": "2026-04-28T10:05:00Z"
}

JavaScript / TypeScript SDK

bash

npm install ironid

typescript

import { IronID } from 'ironid';

const client = new IronID({ apiKey: process.env.IRONID_API_KEY });

// Certify a file
const cert = await client.certify({
  file: fs.readFileSync('photo.jpg'),
  filename: 'photo.jpg',
  metadata: { author: 'Jane Doe', location: 'Paris' },
  webhookUrl: 'https://myapp.com/webhooks/ironid',
});

console.log(cert.certified_url);    // share & verify
console.log(cert.verification_url); // public proof link

// Verify a file
const result = await client.verify('photo.jpg');
console.log(result.is_certified); // true

// Manage API keys
const key = await client.keys.create({ name: 'Production' });
console.log(key.raw_key); // shown once — store securely

Python SDK

bash

pip install ironid

python

from ironid import IronID
import os

client = IronID(api_key=os.environ["IRONID_API_KEY"])

# Certify a file
with open("photo.jpg", "rb") as f:
    cert = client.certify(
        f,
        filename="photo.jpg",
        metadata={"author": "Jane Doe", "location": "Paris"},
    )

print(cert.certified_url)    # share & verify
print(cert.verification_url) # public proof link

# Verify a file
result = client.verify("photo.jpg")
print(result.is_certified)   # True

# Manage API keys
with IronID(api_key=os.environ["IRONID_API_KEY"]) as client:
    keys = client.keys.list()
    print(keys[0].name)

Error Codes

HTTP Code	Code	Description
400	INVALID_BODY	Malformed request or invalid parameter.
401	UNAUTHORIZED	Missing, invalid, or revoked API key.
403	FORBIDDEN	Action not allowed for this plan or role.
404	NOT_FOUND	Resource not found.
413	FILE_TOO_LARGE	File exceeds the limit (100 MB).
415	UNSUPPORTED_MIME	Unsupported file type.
422	QUOTA_EXCEEDED	Monthly certification quota exhausted.
429	RATE_LIMITED	Too many requests. Wait before retrying.
500	INTERNAL_ERROR	Internal server error.