ECL API Reference

The APIs described in this page is only available for Enterprise Edition users.

Before using the APIs, the authentication token must be obtained according to this procedure. Then attach the token in the “X-Auth-Token” header, in the HTTP request.

The API endpoint URL can be found at here.

API List

Description Method Endpoint
Get apps list GET /tenants/{tenant_id}/apps
Create new app POST /tenants/{tenant_id}/apps
Get app GET /tenants/{tenant_id}/apps/{app_id}
Delete app DELETE /tenants/{tenant_id}/apps/{app_id}
Update app PUT /tenants/{tenant_id}/apps/{app_id}
Get app secret key GET /tenants/{tenant_id}/apps/{app_id}/secretkey
Renew app secret key POST /tenants/{tenant_id}/apps/{app_id}/secretkey

Get apps list

Request

Request URL

GET /tenants/{tenant_id}/apps

Request Parameters

Name Type Description
expandApps boolean Expands the apps array to contain the whole body of the app object (except the secret key) when true. Only returns id, apikey and description when false. True if present, default is false. Can also explicitly set expandApps=true or expandApps=false.

Request Format

None

Response

Response Codes

Code Condition
200 Normal end
403 Not authenticated
- Tenant is suspended
- Tenant is Deleted

Response Parameters

Name Type Description
- Array<App> An array of apps belonging to this tenant. Information returned depends on whether expandApps parameter was true or not.

Response Format

With expandApps set.

[
  {
    "id": "{app_id}",
    "apikey": "{apikey_id}",
    "description": "<description>",
    "domains": [],
    "permissions": [],
    "usage_summary": {
      "2018/06": {
        "signaling":0,
        "turn":0,
        "sfu":0
      },
      "2018/07": {
        "signaling":0,
        "turn":0,
        "sfu":0
      }
    },
    "status": "<status>",
    "recording": {
      "status": "<recording_status>",
      "bucket_name": "<recording_bucket_name>"
    },
    "created_at": "2016-12-09T21:50:21Z",
    "updated_at": "2016-12-09T21:50:21Z"
  },
  {
    "id": "{app_id}",
    "apikey": "{apikey_id}",
    "description": "<description>",
    "domains": ["<domain1>", "<domain2>"],
    "permissions": ["<permission>"],
    "usage_summary": {
      "2018/06": {
        "signaling":0,
        "turn":0,
        "sfu":0
      },
      "2018/07": {
        "signaling":0,
        "turn":0,
        "sfu":0
      }
    },
    "status": "<status>",
    "recording": {
      "status": "<recording_status>",
      "bucket_name": "<recording_bucket_name>"
    },
    "created_at": "2016-12-09T22:50:21Z",
    "updated_at": "2016-12-10T23:50:21Z"
  }
]

Without expandApps set.

[
  {
  "id": "{app_id}",
  "apikey": "{apikey_id}",
  "description": "<description>"
  },
  {"id": "{app_id}",
  "apikey": "{apikey_id}",
  "description": "<description>"
  }
]

Create new app

Request

Request URL

POST /tenants/{tenant_id}/apps

Request Parameters

Name Type Description
description string Optional. A description of the app. Up to 128 chars.
domains Array<string> Optional. The domains permitted for the app.
permissions Array<string> Optional. The permissions enabled for the app. “TURN”, “SFU”, “USER_LIST”, “PEER_AUTHENTICATION”, and “RECORDING” can be set.
status string Optional. The app status. One of "active" or "suspended".
recording_bucket_name string Optional. The Google Cloud Storage bucket name to save recorded data
recording_service_account_key string Optional. The service account key to save recorded data

Request Format

{
  "description": "<description>"
}

Response

Response Parameters

Name Type Description
id string The app id
apikey string The app apikey
description string A description of the app
domains Array<string> A list of domains this app is permitted on.
permissions Array<string> An list of permissions this app has.
status string The status of the app
recording.status string The status of the recording permission. One of "active" or "unavailable"
recording.bucket_name string The Google Cloud Storage bucket name to save recorded data.
created_at string When this app was created.
updated_at string When this app was last updated.

Response Codes

Code Condition
200 Normal end
400 Description exceeding the maximum length
- Domain exceeding the maximum length
- Invalid domain format
- Invalid status
- Invalid permissions
403 Not authenticated
- Tenant is suspended

Response Format

{
  "id": "{app_id}",
  "apikey": "{apikey_id}",
  "description": "<description>",
  "domains": [],
  "permissions": [],
  "usage_summary": {
    "2018/06": {
      "signaling":0,
      "turn":0,
      "sfu":0
    },
    "2018/07": {
      "signaling":0,
      "turn":0,
      "sfu":0
    }
  },
  "status": "active",
  "recording": {
    "status": "<recording_status>",
    "bucket_name": "<recording_bucket_name>"
  },
  "created_at": "2016-12-09T21:50:21Z",
  "updated_at": "2016-12-09T21:50:21Z"
}

Get app

Request

Request URL

GET /tenants/{tenant_id}/apps/{app_id}

Request Parameters

None

Request Format

None

Response

Response Parameters

Name Type Description
id string The app id
apikey string The app apikey
description string A description of the app
domains Array<string> A list of domains this app is permitted on.
permissions Array<string> An list of permissions this app has.
status string The status of the app
recording.status string The status of the recording permission. One of "active" or "unavailable"
recording.bucket_name string The Google Cloud Storage bucket name to save recorded data.
created_at string When this app was created.
updated_at string When this app was last updated.

Response Codes

Code Condition
200 Normal end
403 Not authenticated
- Tenant is suspended
- Tenant is Deleted

Response Format

{
  "id": "{app_id}",
  "apikey": "{apikey_id}",
  "description": "<description>",
  "domains": ["<domain1>", "<domain2>"],
  "permissions": ["<permission>"],
  "usage_summary": {
    "2018/06": {
      "signaling":0,
      "turn":0,
      "sfu":0
    },
    "2018/07": {
      "signaling":0,
      "turn":0,
      "sfu":0
    }
  },
  "status": "<status>",
  "recording": {
    "status": "<recording_status>",
    "bucket_name": "<recording_bucket_name>"
  },
  "created_at": "2016-12-09T21:50:21Z",
  "updated_at": "2016-12-09T21:50:21Z"
}

Delete app

Request

Request URL

DELETE /tenants/{tenant_id}/apps/{app_id}

Request Parameters

None

Request Format

None

Response

Response Parameters

None

Response Codes

Code Condition
200 Normal end
403 App doesn’t exist
- Not authenticated
- Tenant is suspended
- Tenant is Deleted

Response Format

{}

Update app

Request

Request URL

PUT /tenants/{tenant_id}/apps/{app_id}

Request Parameters

Name Type Description
description string Optional. A description of the app
domains Array<string> Optional. The domains permitted for the app
permissions Array<string> Optional. The permissions enabled for the app. “TURN”, “SFU”, “USER_LIST”, “PEER_AUTHENTICATION”, and “RECORDING” can be set.
status string Optional. The app status. One of "active" or "suspended"
recording_bucket_name string Optional. The Google Cloud Storage bucket name to save recorded data
recording_service_account_key string Optional. The service account key to save recorded data

Request Format

{
  "description": "<description>",
  "status": "<status>",
  "permissions": ["RECORDING"],
  "recording_bucket_name": "<recording_bucket_name>",
  "recording_service_account_key": "<recording_service_account_key>",
  "domains": ["<domain1>", "<domain2>"]
}

Response

Response Parameters

Name Type Description
id string The app id
apikey string The app apikey
description string A description of the app.
domains Array<string> A list of domains this app is permitted on.
permissions Array<string> An list of permissions this app has.
status string The status of the app.
recording.status string The status of the recording permission. One of "active" or "unavailable"
recording.bucket_name string The Google Cloud Storage bucket name to save recorded data.
created_at string When this app was created.
updated_at string When this app was last updated.

Response Codes

Code Condition
200 Normal end
400 Description exceeding the maximum length
- Domain exceeding the maximum length
- Invalid domain format
- Invalid status
- Invalid permissions
403 Not authenticated
- Tenant is suspended
- App doesn’t exist

Response Format

{
  "id": "{app_id}",
  "apikey": "{apikey_id}",
  "description": "<description>",
  "domains": ["<domain1>", "<domain2>"],
  "permissions": ["<permission>"],
  "usage_summary": {
    "2018/06": {
      "signaling":0,
      "turn":0,
      "sfu":0
    },
    "2018/07": {
      "signaling":0,
      "turn":0,
      "sfu":0
    }
  },
  "status": "<status>",
  "recording": {
    "status": "<recording_status>",
    "bucket_name": "<recording_bucket_name>"
  },
  "created_at": "2016-12-09T21:50:21Z",
  "updated_at": "2016-12-09T23:20:21Z"
}

Get an app secret key

Request

Request URL

GET /tenants/{tenant_id}/apps/{app_id}/secretkey

Request Parameters

None

Request Format

None

Response

Response Parameters

Name Type Description
secretkey string The secret key for the app

Response Codes

Code Condition
200 Normal end
403 Not authenticated
- App doesn’t exist
- Tenant is suspended
- Tenant is Deleted

Response Format

{
  "secretkey": "<secretkey>"
}

Regenerate app secret key

Request

Request URL

POST /tenants/{tenant_id}/apps/{app_id}/secretkey

Request Parameters

None

Request Format

None

Response

Response Parameters

Name Type Description
secretkey string The new secret key for the app

Response Codes

Code Condition
200 Normal end
403 Not authenticated
- App doesn’t exist
- Tenant is suspended
- Tenant is Deleted

Response Format

{
  "secretkey": "<secretkey>"
}