Internal GCManage API

Authentication With GCManage 2.0

Before calling any of the Internal GCAPI services, an application must authenticate and obtain a "passcode" from GCManage. GCManage provides a service to fetch the accounts available to a user and their "passcodes" given the user's name and password. This service is useful when implementing an third-party login page for GCManage or when calling services on Internal GCAPI. The format for calling this function is:

https://[GCManage-URL]/services.php?sname=LoginService&username=[username]&password=[plain-text-password]&listaccounts=true

The result of the call will be be a JSON encoded string that includes a list of accounts that this user can access:

{
   "result": "OK",
   "id": "c07c11ee-3a27-47e5-9c81-7857de364cdc",
   "lastLogin": "never",
   "accounts": [
       {
           "accountName": "...",
           "systemId": "...",
           "passcode": "...",
           "url": "..."
       },
       ... 
   ]
}

• result: OK if the call succeeded, ERROR otherwise
• errorMessage: Only appears if result is ERROR. Explanation of why call failed
• id: User's unique ID
• lastLogin: User's last login date/time
• accounts: Array of accounts this user has access to
• accountName: Long name for the account
• systemId: ID of associated hardware for the account
• passcode: Effectively the "password" for the system. The passcode changes daily in the very early morning, so it needs to be fetched again every day
• url: Base URL used to communicate with the system

Accessing Internal GCAPI From GCManage2

The proxy systems use on GCManage2 for external users accessing the API is not always listening. This is a security feature; proxies timeout after 30 minutes of inactivity and are opened on demand.

If you need to talk to Internal GCAPI, rather than calling LoginService, you may call the OpenProxyService instead.

OpenProxyService

The format for calling this function is:

https://[GCManage-URL]/services.php?sname=OpenProxyService&username=[username]&password=[plain-text-password]&system_id=[system-id]

Results look like:

{
    "result": "OK",
    "accountName": "Account Name",
    "system_id": "314XXX",
    "url": "https://[GCManage-URL]:[Port Number]/"
    "passcode": "XXXXXX"
}

On OK result, the proxy is listening and you may call down to GCAPI using the returned URL and passcode of the system. Note that the port will timeout after 30 minutes of inactivity. You will need to recall this service to reopen the port if this happens. It is safe to call this service even if the port is already active.

Legacy Authentication With GCManage 1.5

Authentication was a little different in GCManage 1.5.x:

https://[GCManage-URL]/services.php?sname=remotelogin&username=[username]&rawpassword=[plain-text-password]

The result of the call will be be a list of accounts, one per line, that this user can access. Each line is of the format:

[como-system-url]@@[passcode]@@[starting-point]@@[account-description]

• como System URL: The URL to use to get to the system, either proxied or direct, based on the caller's location and other various elements on the server
• passcode: Effectively the "password" for the system. The passcode changes daily in the very early morning, so it needs to be fetched again every day
• Starting Point: The initial menu screen the user sees when connecting to the system. Either "main" for the Main Menu or "tv" for the TV Operations Page
• Account Description: An identifier giving various information about the account