Docs‎ > ‎API Creator‎ > ‎Security‎ > ‎

Manage Users with the REST API

You can manage your users using the default built-in authentication manager.

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

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

Use the following process to manage 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:

$.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);
  }
});

Use the same username/password combination that you use to log into API Creator. The URL you use depends on your installation. This example shows a URL for evaluation accounts.

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 an auth token. This auth token is typically good for 24 hours (you can change this value using Live API Creator).

Create a New User

Issue the following command:

$.ajax({
  type: "post",
  url: 'https://server.acme.com/rest/abl/admin/v2/users',
  dataType: "json",
  contentType: "application/json",
  headers: {
    Authorization: "CALiveAPICreator " + APIKEY + ":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. Use the ident of your project for the project_ident value.

Tip: You can get the ident value from API Creator. Open your API project and go to the Create, API Properties page. The value is in the URL fragment field.

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 " + APIKEY + ":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 attachment.

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