Integration handbook

The commitments between the OpenIRIS association and member integrations — what you can rely on, and what we ask of you. This is the page for your IT security and procurement reviews.

Versioning promise

• The v1 contract is additive-only: new endpoints and new optional fields may appear; existing fields are never renamed, removed, retyped, or made required within v1.
• Breaking changes ship as /v2/… routes; v1 keeps working alongside.
• The wire contract is machine-checked on every change — the published reference is generated from the running service, not hand-maintained.
• Build tolerant readers: ignore JSON fields you don't recognise.

Deprecation policy

• Nothing in v1 is removed without a successor and a minimum 12-month notice.
• Notice goes to the named integration contact on every affected key and the changelog. Because the association knows every consumer, we can and will contact affected members individually before anything is switched off.

Key security

• Keys are shown once at issuance and stored hashed. Treat them like passwords: secret manager, never in URLs, repositories, or tickets.
• Rotation without downtime: issue a second key for the same integration, switch your job over, revoke the old one. We recommend annual rotation and immediate rotation on staff departure.
• Revocation is immediate — a revoked key fails on its next request.
• Every authenticated call is audit-logged per key.
• Scope minimisation: request only what the integration uses. In particular, users:read exposes researcher contact details — an ERP export job has no need for it. This is also your GDPR data-minimisation story.

Rate limits & fair use

• Default 600 requests/minute per key. Limits protect the shared platform all members use, not to meter you.
• Needing more is fine — nightly full-sync jobs at large members qualify for a per-key raise. Ask via the support channel with the key name and expected pattern.
• Be a good neighbour: schedule bulk jobs off-peak for your provider's timezone, use delta filters instead of full pulls, and honour Retry-After on 429s.

Environments

• oi_test_ keys target the test environment; oi_live_ keys target production. Develop and rehearse against test — its data is safe to write.
• Base URLs and test-environment onboarding details are provided at key issuance.

Support

• Feature requests & contract feedback: the Public API forum — it is genuinely read; several live endpoints exist because members asked there.
• Faults: your usual OpenIRIS support channel. Always include the trace_id from the error response and the approximate timestamp (UTC) — it lets us find the exact request in seconds.
• Keep your key's integration contact current — it is the address for changelog, deprecation, and incident notices.

Membership lifecycle

API access is a benefit of OpenIRIS association membership. Keys belong to the member organisation and are revoked when membership ends; data created through the API (cost centers, memberships, export acknowledgements) remains part of the institution's OpenIRIS records under the existing membership agreement.