Difference between revisions of "Internal GCManage API"

From GrandCare Systems
Jump to navigation Jump to search
m (Eumhoefer moved page GCManage API to Internal GCManage API)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=Authentication With GCManage 2.0=
=Authentication With GCManage 2.0=
Before calling any of the [[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 [[GCAPI]]. The format for calling this function is:
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
  https://[GCManage-URL]/services.php?sname=LoginService&username=[username]&password=[plain-text-password]&listaccounts=true


Line 28: Line 28:
* 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
* 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
* 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=
=Legacy Authentication With GCManage 1.5=
Authentication was a little different in GCManage 1.5.x:
Authentication was a little different in GCManage 1.5.x:
  http://[GCManage-URL]/services.php?sname=remotelogin&username=[username]&password=[php-crypted-password]
  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:
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:

Latest revision as of 16:49, 10 July 2017

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