Docs‎ > ‎Logic Designer‎ > ‎Security‎ > ‎

Managing users with the REST API

There are two main cases for user management:

1 - If you use an outside authentication manager (StormPath, Active Directory, ...)

To manage your users, you will need to interact with the third-party service. The details depend on the service. This page won't be helpful to you.

2 - If you use the default built-in authentication manager

You can manage users using the Logic Designer.
If you want to perform certain tasks programmatically, you can do so using the REST API.

There is a small mini-app attached at the bottom of this page. It contains mostly the same code as this page, but can be run directly in a browser.

The following examples are in JavaScript/jQuery, you'll need to adapt them to your programming language and framework(s). 
The variables in ALL CAPS need to be replaced with real values.

Step 1: obtain an API key

$.ajax({
  type: 'post',
  url: 'https://eval.espressologic.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);
  }
});

You'll want to use the same username/password combination that you use to log into the Logic Designer.
The URL you use depends on your installation -- the one shown here is for evaluation accounts.

This will give you an API key, typically good for 24 hours (you can change that value in the Logic Designer):

Response:

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

Step 2: create a new user

$.ajax({
  type: "post",
  url: 'https://demodev.espressologic.com/rest/abl/admin/v2/users',
  dataType: "json",
  contentType: "application/json",
  headers: {
    Authorization: "Espresso " + 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);
  }
});


Note that, even though you send the password in clear (but over SSL), it will actually be salted and hashed internally -- user passwords are never stored.

The project_ident value should be the ident of your project. You can get it from the Logic Designer by, for instance, selecting the Resources page for your project, and looking at the URL.

Response:
{
  "@metadata": {
    "href": "https://eval.espressologic.com/rest/abl/admin/v2/users/1010",
    "resource": "users",
    "verb": "INSERT",
    "links": [
      {
        "href": "https://demodev.espressologic.com/rest/abl/admin/v2/user_logins?filter=user_ident%20%3D%201010",
        "rel": "children",
        "role": "user_loginsList",
        "type": "https://demodev.espressologic.com/rest/abl/admin/user_logins"
      },
      {
        "href": "https://demodev.espressologic.com/rest/abl/admin/v2/projects?filter=ident%20%3D%201000",
        "rel": "parent",
        "role": "fk_users_project",
        "type": "https://demodev.espressologic.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
}

Step 3: change user's password

Here we use the newUser object from the last example and modify the password:

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: "Espresso " + 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); 
  }
});

Response:
{
  "@metadata": {
    "href": "https://demodev.espressologic.com/rest/abl/admin/v2/users/1010",
    "resource": "users",
    "verb": "UPDATE",
    "links": [
      {
        "href": "https://demodev.espressologic.com/rest/abl/admin/v2/user_logins?filter=user_ident%20%3D%201010",
        "rel": "children",
        "role": "user_loginsList",
        "type": "https://demodev.espressologic.com/rest/abl/admin/user_logins"
      },
      {
        "href": "https://demodev.espressologic.com/rest/abl/admin/v2/projects?filter=ident%20%3D%201000",
        "rel": "parent",
        "role": "fk_users_project",
        "type": "https://demodev.espressologic.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
}

Full example

These examples are wrapped into a barebones HTML/jQuery mini-app, which is attached to the bottom of this page.
You *will* need to edit the file before loading it in your browser. The comments will indicate what needs to be changed.