Omada Open API

https://use1-omada-northbound.tplinkcloud.com/doc.html
Admin
Omada Open API provides RESTful access to Omada Controller services, enabling users to integrate...
Tokens:6,096
Snippets:73
Trust Score:9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Access API Interface

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

Example of calling a protected API endpoint by providing the access token in the Authorization header.

```bash
curl "https://localhost:8043/openapi/v1/de382a0e78f4deb681f3128c3e75dbd1/sites?pageSize=1&page=1" -H 'content-type:application/json' -H 'Authorization:AccessToken=AT-RCio7FS9p46wSD7dM8CwNQA7ylcrmAcV' -X GET -i -k --insecure
```

```json
{"errorCode":0,"msg":"Success.","result":{"totalRows":1,"currentPage":1,"currentSize":1,"data":[{"siteId":"640effd1b3f2ae5b912275ec","name":"323233232","region":"China mainland","timeZone":"UTC","scenario":"Hotel","type":0}]}}
```

--------------------------------

### POST /openapi/authorize/token

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

Obtain an access token using client credentials by providing the omadacId, client_id, and client_secret.

```APIDOC
## POST /openapi/authorize/token

### Description
Obtain an access token using the client credentials mode. This method allows direct authentication without needing an authorization code.

### Method
POST

### Endpoint
https://localhost:8043/openapi/authorize/token

### Parameters
#### Query Parameters
- **grant_type** (string) - Required - Must be set to "client_credentials"

#### Request Body
- **omadacId** (string) - Required - The msp id or customer id
- **client_id** (string) - Required - The client ID
- **client_secret** (string) - Required - The client secret

### Request Example
{
  "omadacId": "de382a0e78f4deb681f3128c3e75dbd1",
  "client_id": "185586e0df424f5ea938de13cba91e01",
  "client_secret": "767372a5258a4fc1a03c57f3d071fc35"
}

### Response
#### Success Response (200)
- **errorCode** (integer) - Status code
- **msg** (string) - Success message
- **result** (object) - Contains accessToken, tokenType, expiresIn, and refreshToken

#### Response Example
{
  "errorCode": 0,
  "msg": "Open API Get Access Token successfully.",
  "result": {
    "accessToken": "AT-bjaJkIMIiekZY6NBufoQO4hdmJTswlwU",
    "tokenType": "bearer",
    "expiresIn": 7200,
    "refreshToken": "RT-3ZjJgcORJSh76UCh7pj0rs5VRISIpagV"
  }
}
```

--------------------------------

### Obtain Access Token

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

Request an access token using an authorization code via a POST request.

```bash
curl "https://localhost:8043/openapi/authorize/token?grant_type=authorization_code&code=OC-y8fyWAyICCqCWw44Oi9GeSr7fQIKHg7g" -H 'content-type:application/json' -d '{"client_id": "29f2fdbeb5a84d50b9b1cdd08cd1a3ff", "client_secret": "cf6b13af0dd045628c9f05f088eb5493"}' -X POST -i -k --insecure
```

```json
{"errorCode":0,"msg":"Open API Get Access Token successfully.","result":{"accessToken":"AT-bllLYOOYASck11SBSDmmHs85lCrkN6Gi","tokenType":"bearer","expiresIn":7200,"refreshToken":"RT-HqvaDuSxEqayM75U2ukTRnBl6f6fiRAc"}}
```

--------------------------------

### POST /openapi/authorize/token (Obtain Access Token)

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

Exchanges an authorization code for an access token.

```APIDOC
## POST /openapi/authorize/token

### Description
Obtains an access token using an authorization code.

### Method
POST

### Endpoint
/openapi/authorize/token

### Parameters
#### Query Parameters
- **grant_type** (string) - Required - Must be "authorization_code"
- **code** (string) - Required - The authorization code obtained previously

#### Request Body
- **client_id** (string) - Required - The client ID
- **client_secret** (string) - Required - The client secret

### Response
#### Success Response (200)
- **accessToken** (string) - The access token
- **tokenType** (string) - The type of token
- **expiresIn** (integer) - Expiration time in seconds
- **refreshToken** (string) - The refresh token
```

--------------------------------

### Obtain Authorization Code via cURL

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

Requests an authorization code using the tokens obtained from the login step. The authorization code is valid for 2 minutes.

```bash
curl "https://localhost:8043/openapi/authorize/code?client_id=29f2fdbeb5a84d50b9b1cdd08cd1a3ff&omadac_id=de382a0e78f4deb681f3128c3e75dbd1&response_type=code" -H 'content-type:application/json' -H 'Csrf-Token:ae6b935c92cf4b1b9f3eb852e20ed2b8' -H 'Cookie:TPOMADA_SESSIONID=9cb86bf3a99e48a59e4f3bb464a3c443' -X POST -i -k --insecure
```

```json
{"errorCode":0,"msg":"Open API Authorize successfully.","result":"OC-9iyxaKVOVMBpYhQ4NryaYBjghj3dTY32"}
```

--------------------------------

### POST /openapi/authorize/login

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

Authenticates a user to the Omada system to obtain a session and CSRF token for subsequent API calls.

```APIDOC
## POST /openapi/authorize/login

### Description
Logs in a user to the Omada system. The authority of the API calls will match the logged-in user.

### Method
POST

### Endpoint
/openapi/authorize/login

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The client ID of the application.
- **omadac_id** (string) - Required - The MSP ID or customer ID.

#### Request Body
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Response
#### Success Response (200)
- **csrfToken** (string) - Token required for subsequent requests.
- **sessionId** (string) - Session identifier required for subsequent requests.

#### Response Example
{
  "errorCode": 0,
  "msg": "Open API Log in successfully.",
  "result": {
    "csrfToken": "51cb83c7d00a4e85b3dd2d6174a614d9",
    "sessionId": "2fc0ca155ab94957a9a9e6a3b00662ea"
  }
}
```

--------------------------------

### Obtain Access Token via cURL

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

Request an access token using the client_credentials grant type. Ensure the request includes the required omadacId, client_id, and client_secret in the body.

```bash
curl "https://localhost:8043/openapi/authorize/token?grant_type=client_credentials" -H 'content-type:application/json' -d '{"omadacId": "de382a0e78f4deb681f3128c3e75dbd1", "client_id": "185586e0df424f5ea938de13cba91e01", "client_secret": "767372a5258a4fc1a03c57f3d071fc35"}' -X POST -i -k --insecure
```

--------------------------------

### POST /openapi/authorize/code

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

Obtains an authorization code after successful login.

```APIDOC
## POST /openapi/authorize/code

### Description
Retrieves an authorization code required for API access. This code is valid for 2 minutes.

### Method
POST

### Endpoint
/openapi/authorize/code

### Parameters
#### Query Parameters
- **client_id** (string) - Required - The client ID of the application.
- **omadac_id** (string) - Required - The MSP ID or customer ID.
- **response_type** (string) - Required - Set to 'code'.

#### Headers
- **Csrf-Token** (string) - Required - The CSRF token obtained from the login step.
- **Cookie** (string) - Required - The session cookie in the format 'TPOMADA_SESSIONID={sessionId}'.

### Response
#### Success Response (200)
- **result** (string) - The authorization code.

#### Response Example
{
  "errorCode": 0,
  "msg": "Open API Authorize successfully.",
  "result": "OC-9iyxaKVOVMBpYhQ4NryaYBjghj3dTY32"
}
```

--------------------------------

### Login to Open API via cURL

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

Performs a POST request to the login endpoint to obtain a csrfToken and sessionId. Ensure these tokens are saved for subsequent API calls.

```bash
curl "https://localhost:8043/openapi/authorize/login?client_id=38f2d1b616434374b3f3215246f39940&omadac_id=beed48c7a2b0ea97c9698408843119f3" -H 'content-type:application/json' -d '{"username":"admin","password":"tplink123"}' -X POST -i -k --insecure
```

```json
{"errorCode":0,"msg":"Open API Log in successfully.","result":{"csrfToken":"51cb83c7d00a4e85b3dd2d6174a614d9","sessionId":"2fc0ca155ab94957a9a9e6a3b00662ea"}}
```

--------------------------------

### Refresh Access Token

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

Obtain a new access token using a valid refresh token when the current access token expires.

```bash
curl "https://localhost:8043/openapi/authorize/token?client_id=185586e0df424f5ea938de13cba91e01&client_secret=767372a5258a4fc1a03c57f3d071fc35&refresh_token=RT-AhzwqCenDCZ84qpBHnZhYs3j2RGw9q8E&grant_type=refresh_token" -H 'content-type:application/json' -X POST -i -k --insecure
```

```json
{"errorCode":0,"msg":"Open API Get Access Token successfully.","result":{"accessToken":"AT-w9veJNQlaK8dH08qEQZCTas6y70IRAii","tokenType":"bearer","expiresIn":7001,"refreshToken":"RT-AhzwqCenDCZ84qpBHnZhYs3j2RGw9q8E"}}
```

--------------------------------

### POST /openapi/authorize/token (Refresh Access Token)

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

Refreshes an expired access token using a valid refresh token.

```APIDOC
## POST /openapi/authorize/token

### Description
Refreshes an access token using a refresh token.

### Method
POST

### Endpoint
/openapi/authorize/token

### Parameters
#### Query Parameters
- **grant_type** (string) - Required - Must be "refresh_token"
- **refresh_token** (string) - Required - The current refresh token

#### Request Body
- **client_id** (string) - Required - The client ID
- **client_secret** (string) - Required - The client secret

### Response
#### Success Response (200)
- **accessToken** (string) - The new access token
- **tokenType** (string) - The type of token
- **expiresIn** (integer) - Expiration time in seconds
- **refreshToken** (string) - The new refresh token
```

--------------------------------

### Authentication Overview

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html#/home

The Omada API uses OAuth 2.0 for authentication. It supports the authorization code flow for user-interactive applications and the client credentials flow for machine-to-machine communication.

```APIDOC
## OAuth 2.0 Authentication

### Description
Omada supports two primary OAuth 2.0 flows: Authorization Code mode and Client Credentials mode. These flows allow clients to obtain access tokens to interact with protected controller resources.

### Authentication Flows
- **Authorization Code Mode**: Requires user interaction via a browser to authorize the client and exchange an authorization code for an access token.
- **Client Credentials Mode**: Used for machine-to-machine communication where the client uses its own credentials to obtain an access token.

### Rate Limits
- **API Call Budget**: 10 requests per second per Omada Pro controller or organization.
```

--------------------------------

### Webhook Message JSON Template

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

The standard JSON structure for webhook messages sent by the Omada Controller.

```json
{
  "Site": " site-name (Only the site-level log will have this field) ", 
  "description": "This is a webhook message from Omada Controller",
  "shardSecret": "shard secret of webhook",
  "text": [
    "content of audit log"
  ],
  "Controller": "USA-Toast",
  "timestamp": 1692128478856
}
```

--------------------------------

### Webhook Message Template

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

The structure of the JSON payload sent by the Omada Controller to configured webhooks.

```APIDOC
## Webhook Message Structure

### Description
This represents the JSON object structure for webhook messages sent from the Omada Controller.

### Payload Fields
- **Site** (string) - Optional - The name of the site (only present for site-level logs).
- **description** (string) - Required - A static description of the webhook message.
- **shardSecret** (string) - Required - The shard secret associated with the webhook.
- **text** (array) - Required - An array containing the content of the audit log.
- **Controller** (string) - Required - The name of the Omada Controller.
- **timestamp** (number) - Required - The epoch timestamp of the event.

### Example
{
  "Site": "site-name",
  "description": "This is a webhook message from Omada Controller",
  "shardSecret": "shard secret of webhook",
  "text": ["content of audit log"],
  "Controller": "USA-Toast",
  "timestamp": 1692128478856
}
```

--------------------------------

### Access Token Response

Source: https://use1-omada-northbound.tplinkcloud.com/doc.html

The JSON response returned upon a successful request, containing the accessToken and related metadata.

```json
{"errorCode":0,"msg":"Open API Get Access Token successfully.","result":{"accessToken":"AT-bjaJkIMIiekZY6NBufoQO4hdmJTswlwU","tokenType":"bearer","expiresIn":7200,"refreshToken":"RT-3ZjJgcORJSh76UCh7pj0rs5VRISIpagV"}}
```
Tokens:
Raw