> For the complete documentation index, see [llms.txt](https://docs.connectedyou.io/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.connectedyou.io/knowledge-base/connectedyou-platform/api-docs/apis-reference.md).

# APIs Reference

The IOH APIs allow you to integrate with the [IoT Orchestration Hub](https://console.connectedyou.io/) and automate workflows programmatically.

* **API Base URL:** [`https://api.connectedyou.io`](https://api.connectedyou.io/)
* For the complete API reference, visit [docs.api.connectedyou.io](https://docs.api.connectedyou.io/#intro).

If you have any questions or need assistance, contact our [support desk](https://connectedyou.atlassian.net/servicedesk/customer/portal/1/group/1/create/10).

### Getting Started

To start using the IOH APIs, follow these steps:

1. **Choose an authentication method** and generate an access token.
2. **Get your Account ID**.
3. **Use the API endpoints** with your access token and Account ID.

***

### Authentication

IOH supports two authentication methods:

* **Username and Password**
* **OAuth 2.0 Client Credentials**

Choose the authentication method that best fits your integration.

{% hint style="warning" %}
 Tokens are valid for **60 minutes**.

* Reuse the same access token for all API requests while it is valid. Do not generate a new access token for every API request. Continue using the existing token throughout its 60-minute validity period, and generate a new token only when the current token is expired or approaching expiry. Repeatedly generating tokens for every request is unnecessary and will cause your integration to reach the authentication rate limit.

**Authentication Rate Limit**

Access-token generation is limited to:

**10 requests per minute**

This rate limit applies to authentication token-generation requests.
{% endhint %}

#### 1. Username and Password

The existing authentication flow uses your IOH username and password.

* **Authentication endpoint** `https://api.connectedyou.io/`

Use this endpoint to authenticate and obtain an access token.

The access token is valid for **60 minutes**. When the token expires, you can authenticate again or use the `refresh_token` provided in the authentication response, where applicable.

#### 2. OAuth 2.0

IOH also supports **OAuth 2.0 Client Credentials** for machine-to-machine integrations.

* **Token endpoint** `https://auth.connectedyou.io/oauth2/token`

**2.1 Create an Auth Client**

Before generating an OAuth 2.0 access token, you need to create an **Auth Client** in the IOH platform.

Navigate to:

**Account → Settings → Auth Clients**

From the **Auth Clients** page, you can:

* Create a new Auth Client.
* Access the credentials required for authentication.
* Create and manage multiple Auth Clients for different integrations or applications.

**2.2 Required Credentials**

The following four parameters are required to generate an OAuth 2.0 access token:

| Parameter       | Value                                                |
| --------------- | ---------------------------------------------------- |
| `client_id`     | Available in the IOH platform under the Auth Client. |
| `client_secret` | Available in the IOH platform under the Auth Client. |
| `scope`         | Available in the IOH platform under the Auth Client. |
| `grant_type`    | `client_credentials`                                 |

***

### Get Your Account ID

After authentication, you need an **Account ID** to work with the IOH APIs.

Use the following API endpoint to retrieve the accounts available to your user or integration:

`https://api.connectedyou.io/v1/users`

Select the Account ID that you want to use for your API operations.

{% hint style="info" %}
You can also find your Account ID directly in the IOH platform under **Account Settings**.

* Account > Settings > Account Info
  {% endhint %}

***

### Using the APIs

Once you have:

* A valid access token
* An Account ID

you can start using the IOH APIs.

All available API operations, request parameters, response formats, and examples are documented in the [IOH API reference](https://docs.api.connectedyou.io/#intro).

**API Base URL:**

`https://api.connectedyou.io/v1`

Select an endpoint from the API reference to view its specific requirements and usage.

***

### Quick Reference

| Item                        | Details                                     |
| --------------------------- | ------------------------------------------- |
| Username/Password Auth      | `https://api.connectedyou.io/`              |
| OAuth 2.0 Token Endpoint    | `https://auth.connectedyou.io/oauth2/token` |
| OAuth 2.0 Grant Type        | `client_credentials`                        |
| Access Token Validity       | 60 minutes                                  |
| Token Generation Rate Limit | 10 requests/minute                          |
| Auth Client Location        | **Account → Settings → Auth Clients**       |

You're now ready to integrate with the IOH APIs.