# 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](https://www.rfc-editor.org/rfc/rfc6749#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:

```mermaid
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

<!-- theme: danger -->
> #### 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

<!-- theme: info -->
> #### 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:

```http
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:**
```bash
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}
```

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

<!-- theme: warning -->
> #### 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:

```http
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:**
```bash
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:

```http
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:**
```bash
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
```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

**Error Response Format:**
```json
{
  "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
5. **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

- **Technical Issues:** Contact your BD representative
- **Integration Support:** Email [dev+support@igloohome.co](mailto:dev+support@igloohome.co)