# Partner Account

## Overview

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 [Individual Account](/home/individual-account).

## Prerequisites

Before starting, ensure you have:

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

## Authentication

### OAuth 2.0 Integration

igloohome uses the OAuth 2.0 Authorization Code flow ([RFC 6749, section 4.1](https://www.rfc-editor.org/rfc/rfc6749#section-4.1)) for secure API access through [iglooconnect](https://connect.igloocompany.co/).

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:

```mermaid
sequenceDiagram
    participant User
    participant App as Your Application
    participant Auth as igloohome Auth Server
    participant API as igloohome API
    participant DB as Your Database

    rect rgb(255, 245, 243)
    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
    end

    rect rgb(248, 248, 248)
    Note over App,Auth: 2. Token Exchange
    App->>Auth: Exchange code for tokens
    Auth-->>App: Return access_token, refresh_token, id_token
    end

    rect rgb(255, 245, 243)
    Note over App,DB: 3. Token Management
    App->>DB: Store tokens securely
    App->>DB: Calculate and store expiry time
    end

    rect rgb(248, 248, 248)
    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
    end

    rect rgb(255, 245, 243)
    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
    end
```

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

| Scope | Description |
| --- | --- |
| igloohomeapi/algopin-permanent | Create permanent access AlgoPIN |
| igloohomeapi/algopin-onetime | Create one-time access AlgoPIN |
| igloohomeapi/algopin-daily | Create daily recurring AlgoPIN |
| igloohomeapi/algopin-hourly | Create hourly recurring AlgoPIN |
| igloohomeapi/create-pin-bridge-proxied-job | Create pins via bridge |
| igloohomeapi/delete-pin-bridge-proxied-job | Delete pins via bridge |
| igloohomeapi/lock-bridge-proxied-job | Lock devices via bridge |
| igloohomeapi/unlock-bridge-proxied-job | Unlock devices via bridge |
| igloohomeapi/get-devices | Retrieve device list |
| igloohomeapi/update-device | Configure device settings |
| igloohomeapi/get-master-pin | Get Master PIN |
| igloohomeapi/get-properties | Get Properties |
| igloohomeapi/get-device-status-bridge-proxied-job | Get device status |
| igloohomeapi/get-battery-level-bridge-proxied-job | Get battery levels |
| igloohomeapi/get-activity-logs-bridge-proxied-job | Get activity logs |
| igloohomeapi/get-job-status | Get job status |
| igloohomeapi/create-ekey-access | Generate bluetooth key |
| igloohomeapi/get-device-activity | Get device activity log |
| igloohomeapi/store-device-activity | Push device activity logs |

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

```bash
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.

## Implementation

### 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}
```

#### Parameters

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

Example request:

```bash
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"
```

#### 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 igloohome 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.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:

```bash
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=https%3A%2F%2Fyourapp.com%2Fcallback
```

#### Success Response

```json
{
  "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

```json
{
  "error": "invalid_request"
}
```

| 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

- 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

### "402 Payment Required" on API calls

**Cause:** The account's igloohome API trial has ended, or its billing grace period has expired
**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

- **Technical Issues:** Contact your BD representative
- **Integration Support:** Email dev+support@igloohome.co