Admin Features

Kii JavaScript SDK has the Admin feature that will let you invoke all methods as an app admin. This feature is particularly useful when you are hosting your own server and want to use our JavaScript SDK on your server.

The first step for using the Admin feature is to create a context of KiiAppAdminContext as shown in the following sample code. If you already have the app administrator token by executing the context.getAppAdminContext() in the server code, you do not need to create the context.

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    // adminContext : KiiAppAdminContext instance
    // Operate entities with adminContext.
  }
).catch(
  function(error) {
    var errorString = error.message;
    // Handle the error.
  }
);

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    // adminContext : KiiAppAdminContext instance
    // Operate entities with adminContext.
  },
  failure: function(errorString, statusCode) {
    // Handle the error.
  }
});

Here, we are putting the ClientID and ClientSecret that are assigned to your application when you create the application on the developer portal. See Checking and Resetting Access Keys to learn how to check your ClientID and ClientSecret.

Note: Your ClientID and ClientSecret are confidential information. You should never disclose them to others, meaning that you should never use the feature when your code is open to the public. The feature is intended to be used in the situation where the code is hidden (e.g. the code is running on your server).
Please read Risk of Leaking Admin Credentials to learn about the risk of leaking your ClientID and ClientSecret.

Executing with app administrator privileges

You can manipulate objects with app administrator privileges by using methods of a KiiAppAdminContext instance. Create target instances such as KiiObject and KiiUser directly or indirectly, with a KiiAppAdminContext instance.

As shown in the left side of the figure below, if you create instances such as KiiObject and KiiUser in the app administrator context and access Kii Cloud with a method of the created instances, the method is executed with privileges of the app administrator.
As shown in the right side of the figure below, if you directly create target instances with a method such as Kii.bucketWithName() and access Kii Cloud with a method of the created instances, the method is executed with privileges of the logged-in user or the anonymous user if the user is not logged in.

App administrator privileges are granted not because the authenticateAsAppAdmin() method is executed but because a KiiAppAdminContext instance creates target instances.

Manipulating a KiiUser as an app administrator

Create a KiiUser instance by calling the userWithID method like the following example:

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    var user = adminContext.userWithID("put existing user id here");
    // KiiUser operation by app admin is available now.
  }
).catch(
  function(error) {
    var errorString = error.message;
    // Handle the error.
  }
);

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    var user = adminContext.userWithID("put existing user id here");
    // KiiUser operation by app admin is available now.
  },
  failure: function(errorString, statusCode) {
    // Handle the error.
  }
});

You will now have full access to the user.

Manipulating a KiiGroup as an app administrator

Creating a new KiiGroup

To create a new KiiGroup, create a KiiGroup instance by executing the groupWithName method first and then save the instance by executing the saveWithOwner method with the group owner's user ID. Please do not use the save method, or you will end up with creating a KiiGroup with no owner.

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    var group = adminContext.groupWithName("new_group_name");
    return group.saveWithOwner("Owner UserID");
  }
).then(
  function(theGroup) {
    // KiiGroup operation by app admin is available now.
  }
).catch(
  function(error) {
    var theGroup = error.target;     // for saveWithOwner()
    var errorString = error.message;
    // Handle the error.
  }
);

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    var group = adminContext.groupWithName("new_group_name");
    group.saveWithOwner("Owner UserID", {
      success: function(savedGroup) {
        // KiiGroup operation by app admin is available now.
      },
      failure: function(theGroup, errorString) {
        // Handle the error.
      }
    });
  },
  failure: function(errorString, errorCode) {
    // Handle the error.
  }
});

Creating a new KiiGroup with ID

By using the registerGroupWithOwnerAndID method, you can create a new KiiGroup with the specified group ID.

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    var ownerId = "owner's user id";
    var groupId = "my-group-1";
    var groupName = "myGroup";
    var members = [];
    members.push(KiiUser.userWithID("member's user id"));
    return adminContext.registerGroupWithOwnerAndID(groupId, groupName, ownerId, members);
  }
).then(
  function(theGroup) {
    // KiiGroup operation by app admin is available now.
  }
).catch(
  function(error) {
    var theGroup = error.target;                  // for registerGroupWithOwnerAndID()
    var addMembersArray = error.addMembersArray;  // for registerGroupWithOwnerAndID()
    var anErrorString = error.message;
    // Handle the error.
  }
);

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    var ownerId = "owner's user id";
    var groupId = "my-group-1";
    var groupName = "myGroup";
    var members = [];
    members.push(KiiUser.userWithID("member's user id"));
    adminContext.registerGroupWithOwnerAndID(groupId, groupName, ownerId, members, {
      success: function(theGroup) {
        // KiiGroup operation by app admin is available now.
      },
      failure: function(theGroup, errorString, addMembersArray) {
        // Handle the error.
      }
    });
  },
  failure: function(errorString, errorCode) {
    // Handle the error.
  }
});

Using an existing KiiGroup

To use an existing KiiGroup, execute the groupWithURI method and create a KiiGroup instance like the following sample code:

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    var group = adminContext.groupWithURI("put existing group uri here");
    // KiiGroup operation by app admin is available now.
    // Need to execute refresh() before accessing the group.
  }
).catch(
  function(error) {
    var errorString = error.message;
    // Handle the error.
  }
);

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    var group = adminContext.groupWithURI("put existing group uri here");
    // KiiGroup operation by app admin is available now.
    // Need to execute refresh() before accessing the group.
  },
  failure: function(errorString, errorCode) {
    // Handle the error.
  }
});

You can also create a KiiGroup instance by calling groupWithID method as shown in the following sample code.

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    var group = adminContext.groupWithID("put existing group ID here");
    // KiiGroup operation by app admin is available now.
    // Need to execute refresh() before accessing the group.
  }
).catch(
  function(error) {
    var errorString = error.message;
    // Handle the error.
  }
);

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    var group = adminContext.groupWithID("put existing group ID here");
    // KiiGroup operation by app admin is available now.
    // Need to execute refresh() before accessing the group.
  },
  failure: function(errorString, errorCode) {
    // Handle the error.
  }
});

In both cases, you will now have full access to the group.

Manipulating a KiiBucket as an app administrator

Create aKiiBucket instance in an application scope by calling the bucketWithName method like the following example:

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    var bucket = adminContext.bucketWithName("bucket_name");
    // KiiBucket operation by app admin is available now.
  }
).catch(
  function(error) {
    var errorString = error.message;
    // Handle the error.
  }
);

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    var bucket = adminContext.bucketWithName("bucket_name");
    // KiiBucket operation by app admin is available now.
  },
  failure: function(errorString, errorCode) {
    // Handle the error.
  }
});

If you create a new bucket, it will have an application scope.
If you instantiate an existing bucket, you will be able to access to this bucket as an app admin.

Manipulating a KiiObject as an app administrator

Create a KiiObject instance by calling the objectWithURI method like the following example:

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    var object = adminContext.objectWithURI("Set the URI of an existing KiiObject here");
    // KiiObject operation by app admin is available now.
    // Need to execute refresh() before accessing the object.
  }
).catch(
  function(error) {
    var errorString = error.message;
    // Handle the error.
  }
);

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    var object = adminContext.objectWithURI("Set the URI of an existing KiiObject here");
    // KiiObject operation by app admin is available now.
    // Need to execute refresh() before accessing the object.
  },
  failure: function(errorString, errorCode) {
    // Handle the error.
  }
});

If you create a new object, it will have an application scope.
If you instantiate an existing object, you will be able to access to this object as an app admin.

Querying KiiUsers as an app administrator

Execute the findUserByUsername method to query KiiUsers like the following example:

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    return adminContext.findUserByUsername("user_name_to_find");
  }
).then(
  function(params) {
    var adminContext = params[0];
    var foundUser = params[1];
    // Do something.
  }
).catch(
  function(error) {
    var adminContext = error.target;    // for findUserByUsername()
    var errorString = error.message;
    // Handle the error.
  }
);

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    adminContext.findUserByUsername("user_name_to_find", {
      success: function(adminContext, foundUser) {
        // KiiUser operation by app admin is available now.
      },
      failure: function(adminContext, errorString) {
        // Handle the error.
      }
    });
  },
  failure: function(errorString, errorCode) {
    // Handle the error.
  }
});

You will now have full access to the user.

Please note that all user attributes will be returned regardless of the setting made on the "Expose Full User Data to Others" option.

The above example queries KiiUsers based on their username. You can also query based on their email addresses and phone numbers by executing the findUserByEmail and findUserByPhone methods, respectively.

Manipulating a KiiTopic as an app administrator

Create an application scope KiiTopic instance by calling the topicWithName method like the following example:

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    var topic = adminContext.topicWithName("topic_name");
    // KiiTopic operation by app admin is available now.
  }
).catch(
  function(error) {
    var errorString = error.message;
    // Handle the error.
  }
);

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    var topic = adminContext.topicWithName("topic_name");
    // KiiTopic operation by app admin is available now.
  },
  failure: function(errorString, statusCode) {
    // Handle the error.
  }
});

Here are a couple of documents that will help you:

See this page to check an example of creating an applcation scope topic.
See this page to check an example of sending push messages to an application scope topic.

Manipulating a KiiThing as an app administrator

Create a KiiThing instance by calling the loadThingWithThingID method like the following example:

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret").then(
  function(adminContext) {
    return adminContext.loadThingWithThingID("put existing thing ID here");
  }
).then(
  function(thing) {
    // KiiThing operation by app admin is available now.
  }
).catch(
  function(error) {
    var errorString = error.message;
    // Handle the error.
  }
);

Kii.authenticateAsAppAdmin("ClientID", "ClientSecret", {
  success: function(adminContext) {
    adminContext.loadThingWithThingID("put existing thing ID here", {
      success: function(thing) {
        // KiiThing operation by app admin is available now.
      },
      failure: function(error) {
        // Handle the error.
      }
    });
  },
  failure: function(errorString, errorCode) {
    // Handle the error.
  }
});

This sample code is getting a KiiThing with the thingID. You can also get a KiiThing with the vendorThingID by executing the loadThingWithVendorThingID method. Also, you can register a new thing with the registerThing method. Please read the JSDoc for more details.

For more information on what you can do with KiiThing, please read the section Leveraging Things with Client SDK.