Getting Started with iglooconnect

Build for others. This guide helps you integrate with igloohome's API using OAuth 2.0 authentication via iglooconnect — for partners and integrators building on behalf of other igloohome account owners, whose end users log in and grant your application scoped access to their own locks. You'll learn how to:

• Set up authentication with iglooconnect
• Obtain and manage access tokens
• Make your first API calls

Managing only your own igloohome account and devices instead? See Getting Started with igloohome API — build for yourself.

Prerequisites

Before starting, ensure you have:

• A valid igloohome business partnership
• Your callback URL(s) ready

Authentication Setup

OAuth 2.0 Integration

igloohome uses the OAuth 2.0 Authorization Code flow (RFC 6749, section 4.1) for secure API access through iglooconnect.

This integration enables your users to authenticate with igloohome and grants your application access to their smart locks.

Authentication Flow Diagram

The following diagram illustrates the complete OAuth 2.0 authentication flow, from initial login through token refresh:

Flow Steps Explained

• User Authentication: The user initiates login within your app and is redirected to the igloohome secure login page.
• Authorization Code: Upon successful authentication, the user is redirected back to your defined callback URL with a temporary authorization code.
• Token Exchange: Your application exchanges this authorization code for long-lived access and refresh tokens.
• Secure Storage: Tokens and their calculated expiration times are stored securely in your database.
• API Access: The access token is used to authenticate requests to igloohome API endpoints.
• Token Refresh: Your application proactively refreshes credentials before they expire to ensure uninterrupted service.

Onboarding

To integrate with iglooconnect, you must first register your application and obtain credentials.

• Prepare Configuration: Determine your production callback URL(s). You can register multiple URLs if needed.
• Request Access: Contact your Business Development representative or the integration team.
• Receive Credentials: You will be issued a unique Client ID to identify your application.

Static Redirect URI

Your callback URLs must be static and use HTTPS. Dynamic URLs or plain HTTP are not supported for security reasons.

• Callback URL: Must be HTTPS and exactly match one of the URLs registered with igloohome.
• Client ID: The unique identifier provided during the onboarding process.

Scopes and Permissions

Scopes define what your application can access. Format: space-separated list of scope names. If no scopes are specified, all permissions are granted.

Available Scopes

Implementation Guide

Initiate Authentication

Redirect users to igloohome's login page:

https://auth.igloohome.co/login?response_type=code&client_id={CLIENT_ID}&redirect_uri={REDIRECT_URI}&scope={SCOPES}&state={STATE}

Parameters

State Parameter Usage

When your app adds a state parameter to a request, the server returns its value to your app when redirecting your user.

Common use cases:

• Security: Guard against Cross-Site Request Forgery (CSRF) attacks.
• Context/Identification: Identify your customer or maintain session state. You can include any data your integration requires to recognize the user or context upon their return.

Note: You can't set the value of a state parameter to a URL-encoded JSON string. To pass a string in that format, base64 encode it, then decode it in your app.

Example request:

curl "https://auth.igloohome.co/login?client_id=your_client_id&response_type=code&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=igloohomeapi%2Fget-devices+openid+profile&state=xyz987"

Error Responses

Successful Authentication

After successful authentication, the server redirects to your callback URL with an authorization code. If a state parameter was provided in the initial request, it is returned here unchanged.

https://{REDIRECT_URI}?code={AUTH_CODE}&state={STATE}

Exchange Authorization Code for Tokens

Make a POST request to exchange the authorization code for access tokens:

POST https://auth.igloohome.co/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {your base64 encoded credentials}

grant_type=authorization_code&client_id={CLIENT_ID}&code={AUTH_CODE}&redirect_uri={REDIRECT_URI}

Example request:

curl --request POST \
  --url https://auth.igloohome.co/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic NThucjFwcjgyMTlj...' \
  --data grant_type=authorization_code \
  --data client_id=58nr1... \
  --data code=86b48b3d-****-****-****-********** \
  --data redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback

Success Response

{
  "id_token": "dmcxd329ujdmkemkd349r",
  "access_token": "eyJz9sdfsdfsdfsd",
  "refresh_token": "dn43ud8uj32nk2je",
  "token_type": "Bearer",
  "expires_in": 86400
}

Response fields:

Error Response

{
  "error": "invalid_request"
}

Token Management

Access tokens expire after 24 hours and must be refreshed using the refresh token. The refresh token itself expires 1 year after the initial login.

Token Refresh Process

When an access token expires, use the refresh token to obtain a new access token:

POST https://auth.igloohome.co/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {your base64 encoded credentials}

grant_type=refresh_token&client_id={CLIENT_ID}&refresh_token={REFRESH_TOKEN}

Example request:

curl --request POST \
  --url https://auth.igloohome.co/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic NThucjFwcjgyMTlj...' \
  --data grant_type=refresh_token \
  --data client_id=58nr1... \
  --data refresh_token=dn43ud8uj32nk2je

Recommended Practices

• Expiry Tracking: Calculate and store expiry timestamp for both access and refresh tokens
• Proactive Refresh: Refresh access tokens before expiry (recommended 1 hour before)
• User Re-authentication: Monitor refresh token expiry and prompt users to re-authenticate before the 1-year limit to prevent API access interruption

When the refresh token nears expiration (recommended 30 days before), prompt users to re-authenticate through the login flow to maintain uninterrupted API access.

Quick Start Checklist

Before You Begin

• Prepare HTTPS callback URL

Implementation Steps

• Redirect user to login page
• Handle callback with authorization code
• Exchange code for tokens
• Store tokens securely
• Make first API call
• Implement token refresh logic

Testing Your Integration

• Authentication Flow: Verify login redirect works
• Token Exchange: Confirm you receive valid tokens
• API Calls: Test with minimal scopes first
• Token Refresh: Verify refresh mechanism works

Troubleshooting

"Invalid redirect_uri"

Cause: Callback URL mismatch Solution: Ensure the redirect_uri exactly matches one of the URLs registered with igloohome

"403 Forbidden" on API calls

Cause: Insufficient scopes Solution: Check that your access token includes the required scope for the API endpoint

"Token expired" errors

Cause: Access token expired (24-hour limit) Solution: Implement automatic token refresh using the refresh_token

Getting Help

• Technical Issues: Contact your BD representative
• Integration Support: Email dev+support@igloohome.com