# Individual Account

## Overview

This guide helps you authenticate with the igloohome API using the OAuth 2.0 Client Credentials flow — for developers integrating their own igloohome account and devices, not anyone else's. You'll learn how to obtain access tokens and make your first API calls.

Building on behalf of other igloohome account owners instead? See [Partner Account](/home/partner-account).

## Prerequisites

- An igloohome account
- Access to the igloohome API portal
- Basic understanding of REST APIs and OAuth 2.0

## Authentication

### OAuth 2.0 Client Credentials Flow

The igloohome API uses the OAuth 2.0 Client Credentials flow for authentication. This flow is designed for server-to-server communication where your application acts on its own behalf.

Reference: [OAuth 2.0 RFC 6749, section 4.4](https://www.rfc-editor.org/rfc/rfc6749#section-4.4)

### Authentication Flow Diagram

The following diagram illustrates the complete authentication process, from obtaining a token to using it and reauthenticating 24 hours later:

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

    rect rgb(255, 245, 243)
    Note over App,Auth: 1. Authentication
    App->>Auth: POST /oauth2/token<br/>scope='igloohomeapi/algopin-onetime'
    Auth-->>App: access_token, expires_in, token_type
    App->>DB: Store token + calculated expiry
    end

    rect rgb(248, 248, 248)
    Note over App,API: 2. API Usage
    App->>API: Create One-Time PIN<br/>Authorization: Bearer {token}
    API-->>App: pin, pinId, success
    end

    rect rgb(255, 245, 243)
    Note over App,Auth: 3. New Token (24h later)
    App->>Auth: POST /oauth2/token (client_credentials)
    Auth-->>App: new access_token
    App->>DB: Update stored token
    end
```

### Step 1: Obtain Your API Credentials

- Log in to your [igloohome API portal](https://web.igloohome.co/api)
- Navigate to the **API Access** section
- Copy your **Client ID** and **Client Secret**

New to igloohome? Connect your igloohome account to the igloohome API portal to start a 30-day free trial.

### Step 2: Encode Your Credentials

Your credentials must be Base64 encoded before use:

- Concatenate your Client ID and Client Secret with a colon: `client_id:client_secret`
- Base64 encode the result: `Base64Encode(client_id:client_secret)`

Example:

```javascript
const clientId = "your_client_id_here";
const clientSecret = "your_client_secret_here";
const credentials = btoa(`${clientId}:${clientSecret}`);
// Result: "eW91cl9jbGllbnRfaWRfaGVyZTp5b3VyX2NsaWVudF9zZWNyZXRfaGVyZQ=="
```

```python
import base64

credentials = base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()
```

```go
credentials := base64.StdEncoding.EncodeToString([]byte(clientID + ":" + clientSecret))
```

```bash
echo -n "client_id:client_secret" | base64
```

This encoded string will be used in the Authorization header as `Basic {credentials}`.

### Step 3: Request an Access Token

Make a POST request to the token endpoint with your encoded credentials.

**Endpoint:** `POST https://auth.igloohome.co/oauth2/token`

#### Required Headers

| Header | Value | Description |
| --- | --- | --- |
| Authorization | `Basic {credentials}` | Your Base64 encoded client credentials |
| Content-Type | `application/x-www-form-urlencoded` | Required for form data |

#### Required Parameters

| Parameter | Value | Description |
| --- | --- | --- |
| grant_type | `client_credentials` | OAuth 2.0 grant type |

#### Optional Parameters

| Parameter | Description |
| --- | --- |
| scope | Space-separated list of permissions. If omitted, 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 |

#### Example Requests

Request all permissions:

```bash
curl --request POST \
  --url https://auth.igloohome.co/oauth2/token \
  --header 'Authorization: Basic {your_encoded_credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials
```

Request specific permissions:

```bash
curl --request POST \
  --url https://auth.igloohome.co/oauth2/token \
  --header 'Authorization: Basic {your_encoded_credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=igloohomeapi/algopin-onetime igloohomeapi/get-devices'
```

### Successful Response

When authentication succeeds, you'll receive a JSON response with your access token:

```json
{
  "access_token": "eyJraWQiOiJKc.....",
  "expires_in": 86400,
  "token_type": "Bearer"
}
```

| Field | Description |
| --- | --- |
| access_token | JWT token for API authentication |
| expires_in | Token lifetime in seconds (86400 = 24 hours) |
| token_type | Always "Bearer" |

## Token Management

Access tokens expire after 24 hours. Client credentials issue no refresh token, so when a token expires, reauthenticate by requesting a new access token with the same call.

### Best Practices

- Store tokens securely
- Calculate expiry time: `current_time + expires_in`
- Request a new token shortly before the current one expires

## Implementation

### Using Your Token

Include your access token in API requests:

```bash
curl --request GET \
  --url https://api.igloohome.co/home/devices \
  --header 'Authorization: Bearer {your_access_token}'
```

### Example 1: One-Time PIN Access

For applications that only need to create one-time access pins, limit your scope for better security:

```bash
curl --request POST \
  --url https://auth.igloohome.co/oauth2/token \
  --header 'Authorization: Basic {credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=igloohomeapi/algopin-onetime'
```

Note: Attempting to create permanent pins with a one-time scope token will result in `403 Forbidden`.

### Example 2: Device Management Application

For applications that need full device control and monitoring:

```bash
curl --request POST \
  --url https://auth.igloohome.co/oauth2/token \
  --header 'Authorization: Basic {credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=igloohomeapi/get-devices igloohomeapi/lock-bridge-proxied-job igloohomeapi/unlock-bridge-proxied-job igloohomeapi/get-device-status-bridge-proxied-job'
```

### Example 3: Property Management System

For comprehensive property management requiring all PIN types and device control:

```bash
curl --request POST \
  --url https://auth.igloohome.co/oauth2/token \
  --header 'Authorization: Basic {credentials}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'scope=igloohomeapi/algopin-permanent igloohomeapi/algopin-onetime igloohomeapi/algopin-daily igloohomeapi/algopin-hourly igloohomeapi/get-devices igloohomeapi/lock-bridge-proxied-job igloohomeapi/unlock-bridge-proxied-job'
```

## Quick Start Checklist

### Before You Begin

- Sign in to the [igloohome API portal](https://web.igloohome.co/api) and open **API Access**
- Copy your **Client ID** and **Client Secret**

### Implementation Steps

- Base64 encode your Client ID and Client Secret
- Request an access token with `grant_type=client_credentials` and the scopes your application needs
- Call the API with the `Authorization: Bearer {access_token}` header
- Reauthenticate when the token expires, 24 hours after issue

### Testing Your Integration

- Request a token and confirm the response includes `access_token` and `expires_in`
- Call `GET https://api.igloohome.co/home/devices` and confirm a 200 response

## Troubleshooting

### Error Responses


When authentication fails, you'll receive an error response:

```json
{
  "error": "error_type"
}
```

### Common Errors

| Error Code | Cause | Solution |
| --- | --- | --- |
| invalid_request | Missing required parameter (e.g., grant_type) | Include all required parameters |
| invalid_client | Invalid Client ID or Secret | Verify credentials in igloohome API portal |
| invalid_scope | Requested scope doesn't exist | Check available scopes list |

### Status Codes

**401 Unauthorized:**

- Verify Base64 encoding is correct
- Check Client ID and Secret are valid

**400 Bad Request:**

- Verify `grant_type=client_credentials` is included
- Check Content-Type header is set correctly
- Validate scope parameter format

**402 Payment Required (on API calls):**

- The account's igloohome API trial has ended, or its billing grace period has expired. Check the account's billing status.