Quickstart

Let's get building.

Ready to stop reading and start coding? Let's get your first Flock App connected in minutes.

In this guide, you will:

1. Get your Sandbox credentials.
2. Generate a Machine Token.
3. Create a custom hotlist.
4. Retrieve it to verify your integration.

Step 1: Apply for Access

Access to the API is controlled to ensure security and responsible use. Whether you are a Customer Developer or a Partner, you need to register your Flock app to get started.

• 👉 Fill out the API Application Form

Once approved, our team will provision a Sandbox developer environment for you and share your credentials securely.

Step 2: Get your Keys

You will receive two critical pieces of information for your Sandbox app:

1. Client ID: The public identifier for your App.
2. Client Secret: Your private key.

🔒

Security Check: Treat your client_secret like a password. Keep it out of your frontend code and version control!.

Step 3: Get a Machine Token

Flock uses OAuth 2.0. For this quickstart, we'll use a Machine Token (Client Credentials Flow). This token represents your backend application and allows you to read and write data.

Here is the cURL to get your first token:

curl --request POST \
     --url https://dev-api.flocksafety.com/oauth/token \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data grant_type='client_credentials' \
     --data client_id='YOUR_SANDBOX_CLIENT_ID' \
     --data client_secret='YOUR_SANDBOX_CLIENT_SECRET' \
     --data audience='com.flocksafety.integrations.dev'

And here is your machine access token:

{
  "access_token": "eyJhbGciOiJIUz...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Step 4: Create a Custom Hotlist

Now, let's make your first write to the API. We will create a simple Custom Hotlist called "My Sandbox List".

curl -X POST "https://dev-api.flocksafety.com/api/v3/hotlists" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My Sandbox List",
       "entries": []
     }'

Expected Response (201 Created):

{
  "id": "abc-123-uuid"
}

Step 5: Verify Your Work

Let's confirm that your list exists by retrieving all hotlists for your organization.

curl -X GET "https://dev-api.flocksafety.com/api/v3/hotlists" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

If you see your "My Sandbox List" in the JSON response, congratulations! You just built your first bidirectional Flock App. 🎉

Next Steps
Now that you're connected, it's time to understand the data you're looking at.

• 👉 Read Platform Concepts to understand Organizations, Devices, Networks, and many more important Flock concepts.
• 👉 Explore Authentication to learn about User-Level OAuth.