igloo
Get API Key
Docs / iglooworks / Getting Started / Partner Account

Partner Account

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

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:

sequenceDiagram participant User as User participant App as Your Application participant Auth as iglooworks Auth Server participant API as iglooworks API participant DB as Your Database Note over User, Auth: 1. Authentication Phase User->>App: Initiates login App->>Auth: Redirect to login page Auth->>User: Display login form User->>Auth: Enter credentials Auth->>App: Redirect with authorization code Note over App, Auth: 2. Token Exchange App->>Auth: Exchange code for tokens Auth->>App: Return access_token, refresh_token, id_token Note over App, DB: 3. Token Management App->>DB: Store tokens securely App->>DB: Calculate and store expiry time Note over App, API: 4. API Operations App->>API: GET /devices (with access_token) API->>App: Return device list App->>API: POST /algopin (create permanent PIN) API->>App: Return PIN and pinId Note over App, Auth: 5. Token Refresh (when needed) App->>Auth: Refresh token request Auth->>App: Return new access_token App->>DB: Update stored tokens

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

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

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
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.iglooworks.co/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic {your base64 encoded credentials}' \
  --data grant_type=refresh_token \
  --data client_id={CLIENT_ID} \
  --data refresh_token={REFRESH_TOKEN}
  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.

Implementation

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:

Parameter Required Description
response_type Yes Must be code
client_id Yes Your client ID from iglooworks
redirect_uri Yes Your callback URL (URL encoded)
scope Yes Space-separated scope list

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

Error Code Description Solution
invalid_request Missing or invalid parameter in the login URL (e.g., response_type, redirect_uri) Check all required parameters are included
unauthorized_client Client is not allowed to use this flow Verify your client with the iglooworks team
access_denied The user declined the requested access Ask the user to sign in and approve again
invalid_scope Requested scope not available Use only supported scopes from the list above

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
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.iglooworks.co/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Authorization: Basic {your base64 encoded credentials}' \
  --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

Field Description
id_token Contains user identity claims (name, email)
access_token JWT token for API authentication
refresh_token Used to obtain new tokens (expires in 365 days)
expires_in Access token lifetime in seconds (86400 = 1 day)
token_type Always "Bearer"

Error Response

Error Response Format:

{
  "error": "invalid_request"
}

Error Types:

Error Description
invalid_request Missing required parameter (e.g., grant_type)
invalid_client Client authentication failed
invalid_scope Invalid scope requested
invalid_grant Authorization code expired or already used

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

"402 Payment Required" on API calls

Cause: The account is billing-suspended, or its iglooworks API trial has ended Solution: Ask the account owner to check their billing status

"Token expired" errors

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

Getting Help