API Versioning
The Turris Public API uses URI-based versioning. Every request path begins with a version, and from v2 onward it also names the kind of organization you are calling as.Path format
Available versions
Both versions are stable and supported.
v2 is not a rewrite: request bodies, query parameters and response shapes are identical to v1. The differences are the URL and three deprecated endpoints that v2 does not carry. See the v1 to v2 migration guide.
Personas
The persona segment identifies which kind of organization the calling credentials belong to. Your credentials determine which persona you may use. Once a persona surface ships, credentials belonging to a different persona get 403 witherrorType invalid_organization_category. A path under a persona that is not served yet is not routed at all, so it returns 404 Not Found.
v1 has no persona segment because it predates this model and serves upstream entities only. That is the reason v2 exists: without a persona in the path there is nowhere to put an agency-facing API. The agency surface is therefore v2-only, and no v1 equivalent will be added.
Four endpoints are shared across personas and carry no persona segment:
POST /v2/auth/jwt, GET /v2/auth/test-oauth, GET /v2/auth/test-restricted-access-token and GET /v2/heartbeat. The access token itself identifies your organization, so the endpoint that issues it, the two that verify it, and the health check cannot be scoped to one persona.Version lifecycle
Stable versions
- Backward compatible: existing fields and behaviours will not change
- Additive changes only: new optional fields may be added
- Long-term support: deprecated with ample notice (minimum 6 months)
Deprecation policy
When a version or an individual endpoint is deprecated:- Announcement: we notify you by email and in the documentation
- Grace period: a minimum of 6 months to migrate
- Sunset: the endpoint may stop responding after the sunset date carried in its
Sunsetheader
Deprecation headers
Deprecated endpoints include these response headers, so your integration can detect a deprecation without reading the changelog:Sunset is an HTTP date, as defined in RFC 8594. If your client logs these headers, you will see a deprecation the first time you call an affected endpoint.
Link carries two relations. rel="deprecation" points at this page. rel="successor-version" names the endpoint that replaces the one you called, so a client can report the replacement without a human reading documentation. The example above is the value returned by dangerously-invite; each deprecated endpoint names its own successor.
The three endpoints currently carrying these headers are listed in the migration guide. All three are absent from v2.
Best practices
Build new integrations on v2
Same shapes as
v1, and it is where new capability landsWatch for Deprecation headers
Log them; they tell you before an announcement reaches your inbox
Test in sandbox first
https://public.api.sandbox.turrisfi.com mirrors productionSubscribe to updates
Version changes are announced in the changelog