Docs / iglooworks / Getting Started / Client Credentials

Open in Claude Open in ChatGPT llms.txt

Getting Started

Overview

This guide will help you authenticate with the iglooworks API using OAuth 2.0 Client Credentials flow. You'll learn how to obtain access tokens and make your first API calls.

Prerequisites

An iglooworks account
Basic understanding of REST APIs and OAuth 2.0

Authentication

OAuth 2.0 Client Credentials Flow

The iglooworks API uses OAuth 2.0 Client Credentials flow for authentication. This flow is designed for server-to-server communication where your application acts on its own behalf.

Reference: OAuth 2.0 RFC 6749, section 4.4

Authentication Flow Diagram

The following diagram illustrates the complete authentication process:

sequenceDiagram participant App as Your Application participant Auth as Auth Server participant DB as Your Database participant API as iglooworks API Note over App, Auth: 1. Authentication App->>Auth: POST /oauth2/token<br/>scope='iglooworksapi/algopin-onetime' Auth->>App: access_token, expires_in, token_type App->>DB: Store token + calculated expiry Note over App, API: 2. API Usage App->>API: Create One-Time PIN<br/>Authorization: Bearer {token} API->>App: pin, pinId, success Note over App, API: 3. Token Refresh (24h later) App->>Auth: POST /oauth2/token (refresh) Auth->>App: new access_token App->>DB: Update stored token

Step 1: Obtain Your API Credentials

Contact BD to obtain your api credentials

Step 2: Encode Your Credentials

Your credentials must be Base64 encoded before use:

Concatenate your Client ID and Client Secret with a colon: client_id:client_secret
Base64 encode the result: Base64Encode(client_id:client_secret)

Example:

const clientId = "your_client_id_here";
const clientSecret = "your_client_secret_here";
const credentials = btoa(`${clientId}:${clientSecret}`);
// Result: "eW91cl9jbGllbnRfaWRfaGVyZTp5b3VyX2NsaWVudF9zZWNyZXRfaGVyZQ=="

import base64

client_id = "your_client_id_here"
client_secret = "your_client_secret_here"
credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()
# Result: "eW91cl9jbGllbnRfaWRfaGVyZTp5b3VyX2NsaWVudF9zZWNyZXRfaGVyZQ=="

package main

import (
    "encoding/base64"
    "fmt"
)

func main() {
    clientId := "your_client_id_here"
    clientSecret := "your_client_secret_here"
    credentials := base64.StdEncoding.EncodeToString([]byte(clientId + ":" + clientSecret))
    // Result: "eW91cl9jbGllbnRfaWRfaGVyZTp5b3VyX2NsaWVudF9zZWNyZXRfaGVyZQ=="
}

# Using command substitution to encode credentials
CLIENT_ID="your_client_id_here"
CLIENT_SECRET="your_client_secret_here"
CREDENTIALS=$(echo -n "${CLIENT_ID}:${CLIENT_SECRET}" | base64)
echo $CREDENTIALS
# Result: "eW91cl9jbGllbnRfaWRfaGVyZTp5b3VyX2NsaWVudF9zZWNyZXRfaGVyZQ=="

This encoded string will be used in the Authorization header as Basic {credentials}.

Step 3: Request an Access Token

Make a POST request to the token endpoint with your encoded credentials.

Endpoint: POST https://auth.iglooworks.co/oauth2/token

Required Headers

Header	Value	Description
`Authorization`	`Basic {credentials}`	Your Base64 encoded client credentials
`Content-Type`	`application/x-www-form-urlencoded`	Required for form data

Required Parameters

Parameter	Value	Description
`grant_type`	`client_credentials`	OAuth 2.0 grant type

Optional Parameters

Parameter	Description
`scope`	Space-separated list of permissions. If omitted, all permissions are granted.

Available Scopes

Scope	Description
`iglooworksapi/create-custom-pin-permanent-job`	Create a job for a permanent custom PIN
`iglooworksapi/create-custom-pin-duration-job`	Create a job for a duration-based custom PIN
`iglooworksapi/create-custom-pin-onetime-job`	Create a job for a one-time custom PIN
`iglooworksapi/unlock-bridge-proxied-job`	Unlock devices via bridge
`iglooworksapi/lock-bridge-proxied-job`	Lock devices via bridge
`iglooworksapi/create-pin-bridge-proxied-job`	Create custom PINs via bridge
`iglooworksapi/delete-pin-bridge-proxied-job`	Delete custom PINs via bridge
`iglooworksapi/edit-pin-bridge-proxied-job`	Edit custom PINs via bridge
`iglooworksapi/delete-pin-job`	Create a job to delete a PIN
`iglooworksapi/get-devices`	Retrieve device list
`iglooworksapi/get-job-status`	Get the status of a specific job
`iglooworksapi/get-master-pin`	Get the master PIN of a device
`iglooworksapi/get-properties`	Retrieve property list
`iglooworksapi/get-access`	Retrieve access list for a property
`iglooworksapi/get-battery-level-bridge-proxied-job`	Get battery levels via bridge
`iglooworksapi/get-device-status-bridge-proxied-job`	Get device status via bridge
`iglooworksapi/get-activity-logs-bridge-proxied-job`	Get activity logs via bridge
`iglooworksapi/create-ekey-access`	Create eKey access
`iglooworksapi/store-device-activity`	Store device activity
`iglooworksapi/get-device-activity`	Get device activity
`iglooworksapi/get-jobs`	Get a list of jobs
`iglooworksapi/get-job-detail`	Get the details of a specific job
`iglooworksapi/update-job-status`	Update the status of a job
`iglooworksapi/algopin-permanent`	Create permanent access AlgoPINs
`iglooworksapi/algopin-duration`	Create duration-based AlgoPINs
`iglooworksapi/algopin-otp`	Create one-time access AlgoPINs (OTP)
`iglooworksapi/get-departments`	Retrieve department list
`iglooworksapi/get-account-detail`	Get account detail

Example Requests

Request all permissions:

curl --request POST \
  --url https://auth.iglooworks.co/oauth2/token \
  --header 'Authorization: Basic {your_encoded_credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials

clientId := "your_client_id_here"
clientSecret := "your_client_secret_here"
encodedCredentials := base64.StdEncoding.EncodeToString([]byte(clientId + ":" + clientSecret))

const params = new URLSearchParams({
  grant_type: 'client_credentials'
});

const response = await fetch('https://auth.iglooworks.co/oauth2/token', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${encodedCredentials}`,
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: params
});

package main

import (
    "encoding/base64"
    "net/http"
    "net/url"
    "strings"
)

func main() {
    // Encode credentials
    clientId := "your_client_id_here"
    clientSecret := "your_client_secret_here"
    encodedCredentials := base64.StdEncoding.EncodeToString([]byte(clientId + ":" + clientSecret))

    // Prepare form data
    data := url.Values{}
    data.Set("grant_type", "client_credentials")

    // Create request
    req, _ := http.NewRequest("POST", "https://auth.iglooworks.co/oauth2/token", strings.NewReader(data.Encode()))
    req.Header.Set("Authorization", "Basic "+encodedCredentials)
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

    // Make the request
    client := &http.Client{}
    response, _ := client.Do(req)
}

import requests
import base64

# Encode credentials
client_id = "your_client_id_here"
client_secret = "your_client_secret_here"
encoded_credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()

# Make the request
response = requests.post(
    'https://auth.iglooworks.co/oauth2/token',
    headers={
        'Authorization': f'Basic {encoded_credentials}',
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    data={
        'grant_type': 'client_credentials',
    }
)

Request specific permissions:

curl --request POST \
  --url https://auth.iglooworks.co/oauth2/token \
  --header 'Authorization: Basic {your_encoded_credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=iglooworksapi/algopin-onetime iglooworksapi/get-devices'

clientId := "your_client_id_here"
clientSecret := "your_client_secret_here"
encodedCredentials := base64.StdEncoding.EncodeToString([]byte(clientId + ":" + clientSecret))

const params = new URLSearchParams({
  grant_type: 'client_credentials',
  scope: 'iglooworksapi/algopin-onetime iglooworks/get-devices'
});

const response = await fetch('https://auth.iglooworks.co/oauth2/token', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${encodedCredentials}`,
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: params
});

package main

import (
    "encoding/base64"
    "net/http"
    "net/url"
    "strings"
)

func main() {
    // Encode credentials
    clientId := "your_client_id_here"
    clientSecret := "your_client_secret_here"
    encodedCredentials := base64.StdEncoding.EncodeToString([]byte(clientId + ":" + clientSecret))

    // Prepare form data
    data := url.Values{}
    data.Set("grant_type", "client_credentials")
    data.Set("scope", "iglooworksapi/algopin-onetime iglooworksapi/get-devices")

    // Create request
    req, _ := http.NewRequest("POST", "https://auth.iglooworks.co/oauth2/token", strings.NewReader(data.Encode()))
    req.Header.Set("Authorization", "Basic "+encodedCredentials)
    req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

    // Make the request
    client := &http.Client{}
    response, _ := client.Do(req)
}

import requests
import base64

# Encode credentials
client_id = "your_client_id_here"
client_secret = "your_client_secret_here"
encoded_credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()

# Make the request
response = requests.post(
    'https://auth.iglooworks.co/oauth2/token',
    headers={
        'Authorization': f'Basic {encoded_credentials}',
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    data={
        'grant_type': 'client_credentials',
        'scope': 'iglooworksapi/algopin-onetime iglooworksapi/get-devices'
    }
)

Successful Response

When authentication succeeds, you'll receive a JSON response with your access token:

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

Field	Description
`access_token`	JWT token for API authentication
`expires_in`	Token lifetime in seconds (86400 = 24 hours)
`token_type`	Always "Bearer"

Using Your Token

Include your access token in API requests:

curl --request GET \
  --url https://api.iglooworks.co/v2/devices \
  --header 'Authorization: Bearer {your_access_token}'

Token Management

Token Expiration

Access tokens expire after 24 hours and must be refreshed daily.

Best Practices

Store tokens securely
Calculate expiry time: current_time + expires_in
Implement automatic token refresh before expiration

Error Responses

When authentication fails, you'll receive an error response:

{
  "error": "error_type"
}

Common Errors

Error Code	Cause	Solution
`invalid_request`	Missing required parameter (e.g.,`grant_type`)	Include all required parameters
`invalid_client`	Invalid Client ID or Secret	Verify credentials in iglooaccess dashboard
`invalid_scope`	Requested scope doesn't exist	Check available scopes list

Troubleshooting

401 Unauthorized:

Verify Base64 encoding is correct
Check Client ID and Secret are valid

400 Bad Request:

Verify grant_type=client_credentials is included
Check Content-Type header is set correctly
Validate scope parameter format

Usage Examples

Example 1: One-Time PIN Access

For applications that only need to create one-time access pins, limit your scope for better security:

curl --request POST \
  --url https://auth.iglooworks.co/oauth2/token \
  --header 'Authorization: Basic {credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=iglooworksapi/algopin-onetime'

Note: Attempting to create permanent pins with a one-time scope token will result in 403 Forbidden.

Example 2: Device Management Application

For applications that need full device control and monitoring:

curl --request POST \
  --url https://auth.iglooworks.co/oauth2/token \
  --header 'Authorization: Basic {credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=iglooworksapi/get-devices iglooworksapi/lock-bridge-proxied-job iglooworksapi/unlock-bridge-proxied-job iglooworksapi/get-device-status-bridge-proxied-job'

Example 3: Property Management System

For comprehensive property management requiring all PIN types and device control:

curl --request POST \
  --url https://auth.iglooworks.co/oauth2/token \
  --header 'Authorization: Basic {credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=iglooworksapi/algopin-permanent iglooworksapi/algopin-onetime iglooworksapi/algopin-daily iglooworksapi/get-devices iglooworksapi/lock-bridge-proxied-job iglooworksapi/unlock-bridge-proxied-job'