# ECL API

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>"
}