Manage API Users

You manage API users in API Creator by adding them, by assigning roles to API users, and by defining globals for API users.
lac52
You manage API users in API Creator by adding them, by assigning roles to API users, and by defining globals for API users.
Prerequisite:
 You have specified the 
built-in authentication
 authentication provider as the authentication provider for your API.
In this article:
 
 
3
 
 
Add API Users
When you create an API using API Creator, 
Layer7 Live API Creator
 creates the API users automatically. You can add API users using the following methods:
When you have specified the 
built-in authentication
 authentication provider as the authentication provider for your API, API Server stores the API users that you add in the admin repository, in the 
apis/<apiurl>/security/users
 directory for your API. It also stores the authentication tokens for API users in the 
apis/<apiurl>/security/authtokens
 directory for your API. 
Layer7 Live API Creator
 persists these authentication tokens for the duration of your API Server session.
For more information about the 
security
 directory, see View your API Definition.
Add API Users using API Creator
  1. With your API open, in the Secure section, click 
    Users
    .
    The API Users page appears.
  2. Above the list of API users, click 
    Add
    .
    An API user is added to the list.
  3. Complete the following fields, and then save your changes:
     
    User name
     
    The user name for the API user.
    Full name
     
    The full name for the API user.
    Password
     
    The password for the API user.
     
    Show password
    Specifies whether to show the characters entered for the password or to hide the password.
     
    Email
     
    The email address for the API user.
     
    Lifespan
    The date and time (in days, hours, and minutes) that the authentication token expires for this API user.
     
    Status
    The status of the API user.
    Values:
     Active or Inactive
The API user information is saved.
Add API Users Programmatically
Use the following process to add API users using the REST API:
The following examples are in JavaScript/jQuery. Adapt them to your programming language and frameworks. Replace the variables in ALL CAPS with real values.
Obtain an Authentication Token
Issue the following command, using the same TeamSpace username/password combination that you use to log in to API Creator:
The URL you use depends on your 
Layer7 Live API Creator
 installation. The following example shows a URL if you are using the single-user demonstration package of 
Layer7 Live API Creator
 that is based on Jetty.
$.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": "2018-07-21T12:41:42.546Z", "lastLoginTs": "2018-07-19T08:37:15.049Z", "lastLoginIP": "123.45.67.89" }
The authentication token is obtained.
This authentication token is typically good for 24 hours.
Create an API User
Issue the following command, using the 
ident
 value for your API as the 
project_ident
 value:
 Get the 
ident
 value from the URL.
$.ajax({
type: "post",
url: 'https://server.acme.com/rest/abl/admin/v2/users',
dataType: "json",
contentType: "application/json",
headers: {
Authorization: "CALiveAPICreator 1234567890abcdef1234: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 request sends the password in clear, but over Secure Sockets Layer (SSL). 
Layer7 Live API Creator
 salts and hashes the password; it does not store the passwords for API users.
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": "2018-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 }
An API user is created.
Change the Password for the API User
If you are using the 
built-in authentication
 authentication provider, you can change API user passwords, as well as user name, email, and other information, using cURL.
The cURL command uses the 
newUser
 object from the previous example and modifies the password for the API user:
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": "2018-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 }
Assign Roles to API Users
For each API user, you can specify a set of authorized roles. After the 
built-in authentication
 authentication provider or the JavaScript authentication provider authenticates the API user login, it authorizes the API user to access permitted REST API endpoints or Data Explorer based on the roles that are defined for that API user.
There is no limit to the number of roles that you can assign to an API user. The list of roles that you can assign to API users are those that you have added in API Creator.
For more information about the list of predefined roles, and how to add new ones, see Authorization and Role-Based Endpoint Access.
Follow-these steps:
 
  1. With your API open, in the Secure section, click 
    Users
    .
    The API Users page appears.
  2. Select the API user for which you want to assign a role.
  3. Click the 
    Roles
     tab.
  4. Select the role that you want to assign to the API user, and then save your changes.
The role is assigned to the API user.
Define Globals for API Users
For each API user, you can specify a set of global values/objects. Globals are variables that API Creator makes available to each transaction so that the transaction can determine to what data the API user should have access. For instance, you might want to read the current API user's employee information so that you can use the API user's department number in your security definitions.
You can use these global values, in addition to those values that you explicitly add, in the resource and security filters that the 
built-in authentication
 authentication provider provides.
For more information about globals, see Authorization and Role-Based Endpoint Access.
Follow these steps:
 
  1. From the API Users page, select the API user for which you want to define a global.
  2. Click the 
    Globals
     tab.
  3. Enter comma-separated lists of values that apply only to the selected API user.
    For example:
    deptNo=US Sales,[email protected]
The global is defined for the API user.