Getting Started with iglooworks code flow integration

Overview

This guide helps you integrate with iglooworks's API using OAuth 2.0 authentication. You'll learn how to:

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

Prerequisites

Before starting, ensure you have:

• A valid iglooworks business partnership
• Your callback URL ready
• Contact with your BD representative

Authentication Setup

OAuth 2.0 Integration

iglooworks api v2 uses OAuth 2.0 Authorization Code flow (RFC 6749, section 4.1) for secure API access.

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

Authentication Flow Diagram

The following diagram illustrates the complete OAuth 2.0 authentication flow:

Flow Steps Explained

1. User Authentication: User clicks login in your app and is redirected to iglooworks's secure login page
2. Authorization Code: After successful login, user is redirected back with a temporary authorization code
3. Token Exchange: Your app exchanges the authorization code for long-lived tokens
4. Secure Storage: Store tokens and calculated expiry times in your secure database
5. API Access: Use the access token to make API calls to igloohome services
6. Token Refresh: Proactively refresh tokens before they expire to maintain seamless access

Getting Started

Current Process: Manual onboarding (automated portal coming soon)

Required Steps:

1. Contact your BD representative or our integration team
2. Provide your callback URL
3. Receive your client ID

Static Redirect URI

Your callback URL must be static and use HTTPS. Dynamic URLs or HTTP are not supported.

What You'll Need:

• Callback URL (must be HTTPS)
• Client ID (provided by iglooworks)

Scopes and Permissions

Scopes define what your application can access. Format Space-separated list of scope names

Important

If no scopes are specified, all permissions are granted.

Available Scopes

Implementation Guide

Initiate Authentication

Redirect users to iglooworks's login page:

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

Parameters:

Example Request:

curl "https://auth.iglooworks.co/login?client_id=your_client_id&response_type=code&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=iglooworksapi%2Fget-devices"

Error Responses

Successful Authentication

After successful authentication, the server redirects to your callback URL with an authorization code:

https://{redirect_uri}?code=AUTH_CODE

Exchange Authorization Code for Tokens

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

POST https://auth.iglooworks.co/oauth2/token
Content-Type: application/x-www-form-urlencoded

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

Example Request:

curl --request POST \
  --url https://auth.iglooworks.co/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data client_id={CLIENT_ID} \
  --data code={AUTH_CODE} \
  --data redirect_uri={REDIRECT_URI}

Success Response

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

Response Fields

Error Response

Error Response Format:

{
  "error": "invalid_request"
}

Error Types:

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.iglooworks.co/oauth2/token
Content-Type: application/x-www-form-urlencoded

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

Example Request:

curl --request POST \
  --url https://auth.iglooworks.co/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data client_id={CLIENT_ID} \
  --data refresh_token={REFRESH_TOKEN}

Recommended Practices

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

Important

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

• Contact BD representative for client ID
• Prepare HTTPS callback URL

Implementation Steps

1. Redirect user to login page
2. Handle callback with authorization code
3. Exchange code for tokens
4. Store tokens securely
5. Make first API call
6. Implement token refresh logic

Testing Your Integration

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

Troubleshooting

Common Issues

"Invalid redirect_uri"

Cause: Callback URL mismatch Solution: Ensure the redirect_uri exactly matches the URL registered with iglooworks

"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