SyferLock Help Center

GridGuard v5.3 REST API Documentation

1. Introduction

This document provides details on the REST Application Programming Interface that can be used to integrate other products and applications with GridGuard.



In the following documentation and in most cases, APPID refers to the realm name. 


2. Application Programming Interface

2.1. Authenticate User




Used to authenticate a user and log the user into the application





Post Payload


  <param name="userid" value="{shortname}"/>

  <param name="appid" value="{appid}"/>

  <param name="gridid" value="{gridid}"/>    

  <param name="gridcode" value="{gridcode}"/>

  <param name=”password” value=”{network/AD password}”,

  <param name="ipAddress" value="{ip address}"/>


Note: Parameters denoted in red are required parameters


20x: return indicates SUCCESS

includes payload in JSON

{ “auth” : boolean, (will be true on success)

 “reason” : String, (only if authentication failure)


401: return indicates bad user id or grid id or grid code

includes payload in JSON

{ “auth” : boolean, (will be false on failure)

 “reason” : String, (only if authentication failure)


500: return indicates FAILURE. Fault / Exception returned in response.

2.2. Update Grid Password Credentials

Update Grid Password Credentials

"userid" and "appid" are required parameters.

Graphic is incorrect

Positions are as follows: 

1 - NW, 2 - NE, 3 - SW, 4 - SE, 5 - N, 6 - S, 7 - W, 8 - E

2.3. Reset User

Reset User

"userid" and "appid" are required parameters.

2.4. Registered User Check

Registered User Check

"userid" and "appid" are required parameters.

2.5. Get Grid

Get Grid

"realm" is a required GET parameter

Graphic is incorrect

Positions are as follows: 

1 - NW, 2 - NE, 3 - SW, 4 - SE, 5 - N, 6 - S, 7 - W, 8 - E


2.6. Register User

Register User

"userid", "appid", "password", "corner" are all required parameters

2.7. Get Realm List

Get Realm List

3. Sample Code

Please note that samples are incomplete in terms of fault handling; please modify as necessary for your application.

3.1. Sample PHP Code

$url = '';
$username = 'johndoe';           // username of user being validated$appid = 'realm-name';           // realm name$ipAddress = "";                 // ip address of client; optional$authString = 'admin:password';  // username:password with administrative access$payload =
    <param name="userid" value="' . $username . '"/>
    <param name="appid" value="' . $appid . '"/>
    <param name="ipAddress" value="' . $ipAddress . '"/>
$httpHeader = array( 'Content-Type: text/xml', \L		      'Authorization: Basic ' . base64_encode($authString));
$ch = curl_init();
// If valid (i.e. not self-signed) cert is installed, this can be removed.
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $httpHeader);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 5);
$result = curl_exec($ch); //execute post
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if(curl_errno($ch)) {
    print "Error: " . curl_error($ch);
curl_close($ch); //close connection
if(($httpCode == 200) && ($result == "OK!")) {
    print "$username is registered\n\n";
else {
    print "$username is not registered\n";
    print("Result : $httpCode, " . print_r($result, true) . "\n\n");

Given above is sample code in PHP that invokes the ‘registered’ API.

3.2. Sample Java Code

package com.syferlock.example;import;import;import;import;import;import;import;import;import;import org.apache.http.HttpEntity;import org.apache.http.HttpHost;import org.apache.http.HttpResponse;import org.apache.http.auth.AuthScope;import org.apache.http.auth.UsernamePasswordCredentials;import org.apache.http.client.AuthCache;import org.apache.http.client.ClientProtocolException;import org.apache.http.client.CredentialsProvider;import org.apache.http.client.methods.HttpPost;import org.apache.http.client.protocol.ClientContext;import org.apache.http.conn.ClientConnectionManager;import org.apache.http.conn.scheme.Scheme;import org.apache.http.conn.scheme.SchemeRegistry;import org.apache.http.conn.ssl.SSLSocketFactory;import org.apache.http.entity.StringEntity;import org.apache.http.impl.auth.BasicScheme;import org.apache.http.impl.client.BasicAuthCache;import org.apache.http.impl.client.BasicCredentialsProvider;import org.apache.http.impl.client.DefaultHttpClient;import org.apache.http.impl.conn.BasicClientConnectionManager;import org.apache.http.params.BasicHttpParams;import org.apache.http.protocol.BasicHttpContext;import org.apache.http.util.EntityUtils;public class PostMethodExample {  public static void main(String args[]) {
    // This section to ignore SSL errors, will not be necessary, if you have a valid SSL certificate \L    // installed on the GridGuard Virtual Appliance    SSLContext sslContext = null;    try {
      sslContext = SSLContext.getInstance("SSL");
      sslContext.init(null, new TrustManager[] {         new X509TrustManager() {          public X509Certificate[] getAcceptedIssuers() { return null; }          public void checkClientTrusted(X509Certificate[] certs, String authType) { }          public void checkServerTrusted(X509Certificate[] certs, String authType) { }
      }, new SecureRandom());
    } catch (NoSuchAlgorithmException e1) {
    } catch (KeyManagementException e) {
    SSLSocketFactory sf = new SSLSocketFactory(sslContext);
    SchemeRegistry schemeRegistry = new SchemeRegistry();
    schemeRegistry.register(new Scheme("https", 443, sf));
    ClientConnectionManager cm = new BasicClientConnectionManager(schemeRegistry);
    DefaultHttpClient httpClient = new DefaultHttpClient(cm, new BasicHttpParams());
    CredentialsProvider credsProvider = new BasicCredentialsProvider();
    credsProvider.setCredentials(new AuthScope("", 443), 
                                 new UsernamePasswordCredentials("admin", "password"));
    HttpHost targetHost = new HttpHost("", 443, "https"); 
    AuthCache authCache = new BasicAuthCache();
    authCache.put(targetHost, new BasicScheme());
    BasicHttpContext localcontext = new BasicHttpContext();
    localcontext.setAttribute(ClientContext.AUTH_CACHE, authCache);        
    String payload ="<action><param name=\"userid\" value=\"johndoe\"/>" +                    "  <param name=\"appid\" value=\"realm-name\"/>" +                    "  <param name=\"ipAddress\" value=\"\"/>" +                    "</action>";
    HttpPost httpPost = new HttpPost("https://ggva.staging.local/gridguard/rest/user/registered");    try {
      StringEntity requestEntity = new StringEntity(payload);
    } catch (UnsupportedEncodingException e) {
    HttpResponse httpResponse;
    try {
      httpResponse = httpClient.execute(targetHost, httpPost, localcontext);
          if((httpResponse.getStatusLine().getStatusCode() == 200) && 
         (EntityUtils.toString(httpResponse.getEntity()).equals("OK!"))) {
         System.out.println("User registered");
      }      else {
        System.out.println("User not registered");
    } catch (ClientProtocolException e) {
    } catch (IOException e) {
    } finally {

Given above is sample code in Java that invokes the ‘registered’ API. The sample makes use of the Apache HTTP client libraries (

URL https://{GridguardServer}/gridguard/rest/user/authenticate
Description Used to authenticate a user and log the user into the application.
Authentication None
Method POST
   <param name="userid" value="{shortname}"/>
 \  <param name="appid" value="{appid}"/>
   <param name="gridid" value="{gridid}"/>    
   <param name="gridcode" value="{gridcode}"/>

   <param name="ipAddress" value="{ip address}"/>

Parameters in red are required.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request


Powered by Zendesk