Authentication Overview
Authentication is a critical part of the development process, but it doesn’t have to be daunting. With the right tools and best practices, you’ll have a secure, smooth authentication flow. Whether you’re handling user-level OAuth or org-level OAuth, we’ve got you covered.
Authentication Basics
Before your app can access customer data or interact with Flock environments, it must go through an authentication process. This involves obtaining the necessary tokens and permissions for your app to function properly. Flock apps use OAuth scopes to govern what they can access. These are added in the app settings when registering your app with the Flock team.
This guide covers authentication options for the Flock Safety API Platform, including Machine-Level OAuth (formerly Org-Level) and the recommended User-Level OAuth (for new endpoints and sensitive data access).
Key Concepts
- OAuth 2.0: Learn how to use OAuth 2.0 to securely authenticate users and request access tokens.
- Tokens: Understand the different types of tokens your app can use (User Tokens and Machine Tokens) and how to manage them.
Developer Benefits of User Tokens
We recommend using User-Level OAuth for new integrations and sensitive endpoints. Key benefits include:
- Access to more endpoints: Certain endpoints require user-level OAuth.
- User permissions replication: User-level OAuth respects Flock Safety role-based access control. Third-party apps automatically inherit device network access permissions and permitted actions, reducing maintenance and security drift.
- Improved security and compliance: All actions are attributed to a specific user, supporting full audit trails within the Flock Safety platform.
- Higher, more accurate usage quotas: User-level OAuth lets each user have their own API quota, giving your app more flexibility and higher usage limits on certain endpoints—perfect for building real-time, on-demand features without hitting organization-level caps.
- Future readiness: New development and enhancements are prioritized for user-level OAuth endpoints.
Choosing the Right OAuth Model
| API | User-Level Support | Machine-Level Support |
|---|---|---|
| LPR Search API | ✅ Supported | ❌ N/A |
| Custom Hotlist API | ✅ Supported | ✅ Supported |
| Device API | 🚧 Planned | ✅ Supported |
| Hotlist Alerts Subscription API | ❌ N/A | ✅ Supported |
| LPR Plate Lookup API | ❌ N/A | ✅ Supported |
| CAD API | ❌ N/A | ✅ Supported |
| Geolocation API | ❌ N/A | ✅ Supported |
| Inbound Alerts API | ❌ N/A | ✅ Supported |
| Vehicle Detections Ingest API | ❌ N/A | ✅ Supported |
Base Server URL
- Production:
https://api.flocksafety.com/ - Development:
https://dev-api.flocksafety.com/
Audience
The audience for the production environment is com.flocksafety.integrations.
Flock may at its discretion make a development sandbox available on its development environment to you. For the development environment, the audience to use is com.flocksafety.integrations.dev.
Updated about 1 month ago