Docs / iglooworks / Getting Started / Individual Account

Open in Claude Open in ChatGPT llms.txt

Individual Account

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. New Token (24h later) App->>Auth: POST /oauth2/token (client_credentials) 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:

# 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=="

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=="
}

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/delete-pin-job`	Delete a PIN access or revoke an eKey
`iglooworksapi/get-devices`	Retrieve device list
`iglooworksapi/get-job-status`	Get the status of a specific job
`iglooworksapi/get-master-pin`	Get a device's admin key
`iglooworksapi/get-properties`	Retrieve property list
`iglooworksapi/get-access`	Get access records
`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-daily`	Create a daily AlgoPIN
`iglooworksapi/algopin-hourly`	Create an hourly AlgoPIN
`iglooworksapi/algopin-onetime`	Create a one-time AlgoPIN
`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

const clientId = "your_client_id_here";
const clientSecret = "your_client_secret_here";
const encodedCredentials = btoa(`${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
});

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',
    }
)

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)
}

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'

const clientId = "your_client_id_here";
const clientSecret = "your_client_secret_here";
const encodedCredentials = btoa(`${clientId}:${clientSecret}`);

const params = new URLSearchParams({
  grant_type: 'client_credentials',
  scope: 'iglooworksapi/algopin-onetime iglooworksapi/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
});

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'
    }
)

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)
}

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"

Token Management

Access tokens expire after 24 hours. Client credentials issue no refresh token, so when a token expires, reauthenticate by requesting a new access token with the same call.

Best Practices

Store tokens securely
Calculate expiry time: current_time + expires_in
Request a new token shortly before the current one expires

Implementation

Using Your Token

Include your access token in API requests:

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

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/algopin-hourly iglooworksapi/get-devices iglooworksapi/lock-bridge-proxied-job iglooworksapi/unlock-bridge-proxied-job'

Quick Start Checklist

Before You Begin

Contact BD to obtain your API credentials

Implementation Steps

Base64 encode your Client ID and Client Secret
Request an access token with grant_type=client_credentials and the scopes your application needs
Call the API with the Authorization: Bearer {access_token} header
Reauthenticate when the token expires, 24 hours after issue

Testing Your Integration

Request a token and confirm the response includes access_token and expires_in
Call GET https://api.igloohome.co/works/devices and confirm a 200 response

Troubleshooting

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 with the iglooworks team
`invalid_scope`	Requested scope doesn't exist	Check available scopes list

Status Codes

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

402 Payment Required (on API calls):

The account's iglooworks API trial has ended, or its billing grace period has expired. Check the account's billing status.