API Access

The Report Forge API allows external systems to read edition data, trigger output generation, and push data into editions programmatically. This page covers API key management, authentication, rate limits, and when to use the API vs. built-in sync integrations.

Access: Workspace Settings → API Access (Workspace Admin only).

---

API key management

Generating an API key

1. Go to Workspace Settings → API Access → + New API key.
2. Configure:

Field	Description
Key name	Descriptive label — shown in logs and the key list
Scope	The set of permissions this key grants (see scopes below)
Expiry	Optional expiry date — keys without expiry are valid until revoked
Project restriction	Optionally restrict the key to specific projects

3. Click Generate key.
4. Copy the key immediately — the full key value is only shown once. It cannot be retrieved after leaving this screen.
5. Store the key in a secrets manager (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, or equivalent).

API key scopes

Scope	What the key can do
read:editions	Read edition data, section data, and field values
write:editions	Create editions, update field values, submit editions
read:blueprints	Read blueprint structure and field definitions
read:outputs	Read output metadata and download generated outputs
write:outputs	Trigger output generation
read:workspace	Read workspace members, projects, and settings
admin	Full access — all read and write operations (use with caution)

Grant the minimum scope required. Most integration use cases require only read:editions or read:editions + write:editions.

Rotating an API key

Rotate keys regularly (at least annually) or whenever a key may have been exposed:

1. Generate a new key with the same scope.
2. Update the key in all consuming systems.
3. Verify integrations work with the new key.
4. Revoke the old key.

Revoking an API key

1. Go to Workspace Settings → API Access.
2. Find the key in the list → click Revoke.
3. The key is immediately invalidated — all requests using it will receive 401 Unauthorized.

---

Authentication

All API requests must include the API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example (curl):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.kazinex.com/report-forge/v1/editions

Example (Python):

import requests

headers = {"Authorization": f"Bearer {api_key}"}
response = requests.get(
    "https://api.kazinex.com/report-forge/v1/editions",
    headers=headers
)

API requests over HTTP (not HTTPS) are rejected. All API traffic must use TLS.

---

Common API endpoints

Endpoint	Method	Scope	Description
/v1/projects	GET	read:workspace	List all accessible projects
/v1/projects/{id}/blueprints	GET	read:blueprints	List blueprints in a project
/v1/blueprints/{id}/editions	GET	read:editions	List editions for a blueprint
/v1/editions/{id}	GET	read:editions	Get a specific edition
/v1/editions/{id}/sections/{name}	GET	read:editions	Get all data for a section
/v1/editions/{id}/sections/{name}/rows	GET	read:editions	Get all rows of a repeating section
/v1/editions	POST	write:editions	Create a new edition
/v1/editions/{id}/submit	POST	write:editions	Submit an edition for review
/v1/outputs/{id}/generate	POST	write:outputs	Trigger output generation
/v1/outputs/{id}/download	GET	read:outputs	Download a generated output file

Full endpoint documentation is available in the API Reference (Workspace Admin link only).

---

Rate limits

Limit	Value
Requests per minute	60 per API key
Requests per hour	1,000 per API key
Maximum response size	10 MB
Maximum payload size (POST/PUT)	5 MB
Concurrent connections	5 per API key

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1716345600

When the rate limit is exceeded, the API returns 429 Too Many Requests. Implement exponential backoff in your integration.

---

API vs. sync vs. manual entry

Choosing the right integration method:

Method	Best for	Latency	Setup effort
API (read)	BI tool integration, external dashboards, downstream data pipelines	Seconds	Moderate
API (write)	Pushing data from external systems (ERP, finance, scheduling) into editions	Seconds	High
SharePoint sync	Syncing a blueprint section with a SharePoint list on a schedule	Minutes	Low
Planner integration	Pulling schedule data from Kazinex Planner into blueprint fields	Real-time	Low
Excel import (paste)	Ad hoc bulk import of repeating section data from a spreadsheet	Manual	None
Manual entry	Regular contributor data entry via the edition form/grid	Manual	None

Use API when:

• You need sub-minute freshness (API responds in seconds).
• The source system can make HTTP requests (ERP, finance platform, scheduling tool).
• You need to write data to Report Forge from an external system automatically.
• You are building a custom integration not covered by built-in sync options.

Use SharePoint sync when:

• Your data lives in a SharePoint list and you don't need real-time sync.
• Setup simplicity is more important than control.

---

Webhook notifications for API integrations

Rather than polling the API for edition status changes, subscribe to webhook events:

Event	Webhook payload includes
edition.submitted	Edition ID, blueprint ID, project ID, timestamp
edition.approved	Edition ID, approving user, timestamp
edition.changes_requested	Edition ID, comment count, timestamp
output.generated	Edition ID, output ID, format, download URL

See the Kazinex Webhooks documentation for webhook configuration.

---

Security best practices

1. Never hardcode API keys in source code, config files, or scripts. Use environment variables or secrets managers.
2. Rotate keys regularly — annually at minimum, or immediately after any suspected exposure.
3. Grant minimum scope — use read:editions unless write access is actually needed.
4. Restrict by project — if an integration only needs one project, restrict the key to that project.
5. Monitor API usage — review the audit log for unusual API call patterns (high volume, unexpected hours, unknown IP addresses).
6. Set key expiry — use expiry dates for time-limited integrations (e.g. a contractor integration that ends when the project closes).

---

What's next

• Data Connections Admin — managing SharePoint and Planner connections
• Audit Log — monitoring API key usage in the audit log
• Reporting Cycle Automation — scheduling automated outputs