Manage Users using the Built-in Authentication Provider

To simplify development, API Creator includes an authentication provider that is selected by default. You can manage users using this built-in authentication provider. The users you add using this authentication provider are stored in the Admin database.

Note: If you use an outside authentication provider, such as StormPath, LDAP, or Active Directory, manage your users using your the third-party service. The details depend on the service.

How to Add Users using API Creator

When you create an API project, the users are created automatically. You can add users and define their roles and globals using the Manage, Users tabs.

For more information about how to define a user's roles and globals, see Role-Based Endpoint Access.

On the Manage, Users, User info tab, click AddThe following image shows the admin user details in the Manage, Users, User info tab:

Note: The admin user shown in this image is not the same as the Admin user by the same name. This admin user is used to simplify initial use of Live API Creator.

How to Add Users Programmatically

If you want to perform certain tasks programmatically, you can do so using the REST API. The following examples are in JavaScript/jQuery. Adapt them to your programming language and framework(s). Replace the variables in ALL CAPS with real values.

Use the following process to add new users:
  1. Obtain an auth token.
  2. Create a new user.
  3. Change the user's password.

Obtain an Auth Token

Issue the following command, use the same username/password combination that you use to log into API Creator:

Note: The URL you use depends on your installation. This example shows a URL for evaluation accounts.

$.ajax({
   type: 'post',
   url: 'https://server.acme.com/rest/abl/admin/v2/@authentication',
   dataType: 'json',
   contentType: 'application/json',
   data: JSON.stringify({
      username: 'USERNAME',
      password: 'PASSWORD'}),
   success: function(data) {
      console.log('API key: ' + data.apikey);},
   error: function(xhr, status, error) {
      console.log('Error getting API key: ' + xhr.responseText);}
 });

The following response is expected:

{
  "apikey": "1234567890abcdef1234567890abcdef",
  "expiration": "2014-07-21T12:41:42.546Z",
  "lastLoginTs": "2014-07-19T08:37:15.049Z",
  "lastLoginIP": "12.345.67.89"
}

You have obtained the auth token.

Note: This auth token is typically good for 24 hours. You can change the expiration value. For more information about changing the expiration value, see Auth Tokens.

Create a New User

Issue the following command, using your API project's ident value as the project_ident value:

Tip: You can get the ident value from API Creator. For more information about the ident value, see API Properties.

$.ajax({
  type: "post",
  url: 'https://server.acme.com/rest/abl/admin/v2/users',
  dataType: "json",
  contentType: "application/json",
  headers: {
  Authorization: "CALiveAPICreator " + 1234567890abcdef1234567890abcdef + ":1"
  },
    data: JSON.stringify({name: 'mmouse', fullname: 'Mickey Mouse',
    status: 'A', password_hash: 'abcd1234', roles: 'Sales rep,Sales Manager',
    data: 'region=West', project_ident: PROJECTIDENT}),
    success: function(data) {
       newUser = data.txsummary[0];
       console.log('New user ident: ' + newUser.ident);
    },
    error: function(xhr, status, error) {
       console.log("Error creating user: " + xhr.responseText);
    }
});

The password is sent in clear (but over SSL). It is salted and hashed internally; user passwords are not stored.

The following response is expected:

{
  "@metadata": {
  "href": "https://server.acme.com/rest/abl/admin/v2/users/1010",
  "resource": "users",
  "verb": "INSERT",
  "links": [
  {
    "href": "https://server.acme.com/rest/abl/admin/v2/user_logins?filter=user_ident%20%3D%201010",
    "rel": "children",
    "role": "user_loginsList",
    "type": "https://server.acme.com/rest/abl/admin/user_logins"
  },
  {
    "href": "https://server.acme.com/rest/abl/admin/v2/projects?filter=ident%20%3D%201000",
    "rel": "parent",
    "role": "fk_users_project",
    "type": "https://server.acme.com/rest/abl/admin/projects"
  }
],
"checksum": "A:10c3568c508688f6"
   },
     "ident": 1010,
     "ts": "2014-07-08T08:16:54.000+0000",
     "name": "mmouse",
     "fullname": "Mickey Mouse",
     "email": null,
     "status": "A",
     "roles": "Sales rep,Sales Manager",
     "data": "region=West",
     "comments": null,
     "apikey_lifespan": null,
     "password_hash": "CPvayvYZpNJikoR9tlKQYptAB8SP5sx+DJkXFPhPi0tT7RtXK4aI47VikVRz1xENt0zpJndqQ1FslNvQ==",
     "password_salt": "0lZ6Mo8mkRr190Q0bhObpTz4RU+3cSOFnNVFK",
     "project_ident": 1000
   }

A new user is created.

Change the User's Password

In this example command, the newUser object from the last example is used and the password is modified:

newUser.password_hash = 'newPassword';
$.ajax({
  type: 'put',
  url: demo.newUser['@metadata'].href, // Note: use URL from object if you have one
  dataType: 'json',
  contentType: 'application/json',
  headers: {
  Authorization: "CALiveAPICreator " + 1234567890abcdef1234567890abcdef + ":1"
},
  data: JSON.stringify(demo.newUser),
  success: function(data) {
    newUser = data.txsummary[0];
    console.log('Updated user password: ' + newUser.password_hash);
    },
  error: function(xhr, status, error) {
console.log("Error updating user: " + xhr.responseText);
    }
});

The following response is expected:

{
"@metadata": {
"href": "https://server.acme.com/rest/abl/admin/v2/users/1010",
"resource": "users",
"verb": "UPDATE",
"links": [
{
"href": "https://server.acme.com/rest/abl/admin/v2/user_logins?filter=user_ident%20%3D%201010",
"rel": "children",
"role": "user_loginsList",
"type": "https://server.acme.com/rest/abl/admin/user_logins"
},
{
"href": "https://sever.acme.com/rest/abl/admin/v2/projects?filter=ident%20%3D%201000",
"rel": "parent", "role": "fk_users_project", "type": "https://serer.acme.com/rest/abl/admin/projects" } ], "checksum": "A:4615d52341f072a1" }, "ident": 1010, "ts": "2014-07-08T08:17:01.000+0000", "name": "mmouse", "fullname": "Mickey Mouse", "email": null, "status": "A", "roles": "Sales rep,Sales Manager", "data": "region=West", "comments": null,
"apikey_lifespan": null,"password_hash": "DPFrIVJ2VTg5srsdw66VnNGVucdZD2ELqTDv5fdL98sGpYKx3TFXL/RHth6GpllTNewwxdY2B6TIst9AA==",
"password_salt": "0lZ6Mo8mkRr190Q0bhObpTz4RU+3cSOFnNVFK",
"project_ident": 1000 }

Use the Full Example

To view the examples in a barebones HTML/jQuery mini-app, see the UserSample.HTML attachment.

Important! Edit the file before loading it in your browser. The comments indicate what you need to change.