Suprema BioStar 2 API
Check the BioStar 2 version and supported API path. Review sessions, identity changes and event handling against the device and platform configuration.
Sources and scopeSource record 25 August 2026
Technical source record: 25 August 2026. Check the linked documentation for current product requirements.
Public Suprema API collection and support documentation reviewed on 25 August 2026; exact BioStar build, licence, device/firmware compatibility, session settings, rate limits, endpoint schemas, old Local API, Device SDK, and TA API behaviour require the target installation contract.
On this page
Overview#
Vendor APIs / Access and identity / Suprema
The current BioStar 2 New Local API is a JSON/HTTPS service integrated into BioStar 2. It is distinct from the older separately installed Local API server, the native BioStar 2 Device SDK, and the separate Time and Attendance (TA) API. Choose the authority plane deliberately: the BioStar server API manages platform state; the Device SDK talks at a lower device integration layer.
Documented interface map#
| Surface | Publicly documented purpose | Version/access boundary |
|---|---|---|
| BioStar 2 New Local API | Users, access groups/levels, credentials, devices, doors, elevators, schedules, events, audits, zones and administration | Integrated from BioStar 2.7.10 onward; exact features evolve by server version |
| Offline/local Swagger | Reads bundled New Local API description without a running server connection | Available from BioStar 2.8.14 according to support page; does not execute or prove behaviour |
| Old Local API server | Earlier separately installed API server | Separate version/licence compatibility; do not mix paths or auth with New Local API |
| BioStar 2 Device SDK | Direct supported device integration | Native SDK package, device/firmware matrix and language/runtime contract apply |
| BioStar 2 TA API | Time and attendance service and Swagger | Added with BioStar 2.8.13; separate service/port/schema from access control API |
Version and lifecycle evidence#
The public API collection showed v2.9.12 revisions dated 11 March 2026 and earlier per release change notes during the 25 August 2026 review. This proves documentation changes tied to that BioStar line; it doesn't mean every installation runs 2.9.12 or that all documented operations work on older builds/devices.
The collection flags a compatibility change from BioStar 2.9.9: trailing slashes are no longer accepted for API URLs. This illustrates why integrations must pin and review seemingly small parsing changes. Maintain a per release contract and don't normalise URLs in a way that defeats documented behaviour.
Authentication and transport#
The official overview requires HTTPS. The login operation returns a bs-session-id used for later authorisation. Use a dedicated least privileged BioStar operator, protect its password and session in memory/secret storage, and never log either. Validate the BioStar server certificate under the site PKI instead of accepting a permanent exception.
Session expiry, concurrency, revocation and failover behaviour must be verified on the target version. Re authenticate safely without replaying a high impact mutation. If a server/UI account uses broad biometric or door privileges, don't reuse it as the API service identity.
Pagination and data contract#
The public collection shows more than one collection pattern: some operations use offset/limit, some use page/limit, and search bodies carry their own conditions/order/total fields. Build endpoint specific pagination adapters. Don't assume page origin or a universal maximum.
Treat identifiers, counts, dates, device fields, event data and binary/photo/biometric content as untrusted. Validate bounds before allocation. Record server/API build and device firmware with every compatibility workaround.
A public global request rate limit was not verified. Bound concurrency conservatively, handle throttling/service unavailable responses and obtain site/vendor limits before bulk enrolment or event backfill.
Events, devices, and biometrics#
The API includes event search and device log workflows. Distinguish device resident logs from server stored events; deletion or synchronisation has different evidence impact. Preserve immutable exported evidence before any retention/destructive operation and authorise those operations separately.
User records can contain cards, faces, fingerprints, photos and other sensitive attributes depending on configuration. Minimize collection, encrypt storage/transit, restrict export, define retention/deletion and avoid logging templates/images. Check lawful basis and jurisdiction before biometric processing.
Device, door, quick action, alarm clear, firmware and user export/delete operations are high impact. Never test wildcards or bulk operations on production. Reconcile server and device state after timeout; a server response doesn't prove all devices synchronised.
Primary sources#
- BioStar 2 API collection, official current API overview, revisions, auth and operation catalogue.
- Using the BioStar 2 New Local API, integrated server and session model.
- BioStar 2 API login, session authorisation guidance.
- Offline Swagger support, version and non runtime documentation boundary.
- BioStar 2 TA API introduction, separate TA surface.
- SDK and API starter guide, old API and Device SDK distinction; verify current packages.