Getting Started with igloohome API

Build for yourself. This guide will help you authenticate with the igloohome API using the OAuth 2.0 Client Credentials flow — for developers integrating their own igloohome account and devices, not anyone else's. You'll learn how to obtain access tokens and make your first API calls.

Building on behalf of other igloohome account owners instead? See Getting Started with iglooconnect — build for others.

Prerequisites

• An igloohome account
• Access to the igloohome API portal
• Basic understanding of REST APIs and OAuth 2.0

Authentication

OAuth 2.0 Client Credentials Flow

The igloohome API uses the 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, from obtaining a token to using it and refreshing it 24 hours later:

Step 1: Obtain Your API Credentials

• Log in to your igloohome API portal
• Navigate to the API Access section
• Copy your Client ID and Client Secret

New to igloohome? Connect your igloohome account to the igloohome API portal to start a 30-day free trial.

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

credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()

credentials := base64.StdEncoding.EncodeToString([]byte(clientID + ":" + clientSecret))

echo -n "client_id:client_secret" | base64

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.igloohome.co/oauth2/token

Required Headers

Required Parameters

Optional Parameters

Available Scopes

Example Requests

Request all permissions:

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

Request specific permissions:

curl --request POST \
  --url https://auth.igloohome.co/oauth2/token \
  --header 'Authorization: Basic {your_encoded_credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=igloohomeapi/algopin-onetime igloohomeapi/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"
}

Using Your Token

Include your access token in API requests:

curl --request GET \
  --url https://api.igloodeveloper.co/igloohome/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

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.igloohome.co/oauth2/token \
  --header 'Authorization: Basic {credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=igloohomeapi/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.igloohome.co/oauth2/token \
  --header 'Authorization: Basic {credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=igloohomeapi/get-devices igloohomeapi/lock-bridge-proxied-job igloohomeapi/unlock-bridge-proxied-job igloohomeapi/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.igloohome.co/oauth2/token \
  --header 'Authorization: Basic {credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=igloohomeapi/algopin-permanent igloohomeapi/algopin-onetime igloohomeapi/algopin-daily igloohomeapi/get-devices igloohomeapi/lock-bridge-proxied-job igloohomeapi/unlock-bridge-proxied-job'