Individual Account

Overview

This guide helps 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 Partner Account.

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 reauthenticating 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:

echo -n "client_id:client_secret" | base64

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

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

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

Quick Start Checklist

Before You Begin

• Sign in to the igloohome API portal and open API Access
• Copy your Client ID and Client Secret

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/home/devices and confirm a 200 response

Troubleshooting

Error Responses

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

{
  "error": "error_type"
}

Common Errors

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 igloohome API trial has ended, or its billing grace period has expired. Check the account's billing status.