Manage API Users using the Built-in Authentication Provider

Manage API Users using the Built-in Authentication Provider
calac41
If your API is using the 
built-in authentication
 authentication provider, you can manage the API users within your API. 
CA Live API Creator
 looks up the API users that you define in API Creator during authentication. This authentication provider is specified for your API by default and is most appropriate for development. It defines the 
@authentication
 RESTful endpoint, the system administrator, and API user-access to the REST API endpoints. This authentication provider uses the 
Default Auth Provider
 authentication method.
For each API user, you can specify a set of authorized roles and global values/objects. You can use these global values, in addition to those values you explicitly add, in the resource and security filters that the 
built-in authentication
 authentication provider provides. After the 
built-in authentication
 authentication provider authenticates the API user login, the API user is authorized to access permitted REST API endpoints or Data Explorer based on the roles that are defined for that API user.
You can add API users, assign roles to API users, and define globals for API users using API Creator. You can associate an authentication token with one or more API user roles.
For more information about the 
Default Auth Provider
 authentication method, see Authentication Providers.
In this article:
2
Add API Users
When you create an API using API Creator, 
CA Live API Creator
 creates the API users automatically. You can add API users using the following methods:
The API users you add using the 
built-in authentication
 authentication provider are stored in API Server's admin database.
Add API Users using API Creator
  1. With your API open, in the Manage 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 API user's user name.
    Full name
    The full name for the API user.
    Password
    The API user's password.
    Show password
    Specifies whether to show the characters entered for the password or to hide the password.
    Email
    If you associate authentication tokens with named API users, associate this API user to an authentication token by defining the email address. The email address becomes the login ID that corresponds to this authentication token.
    Optional:
     Yes
    Lifespan
    The date and time (in days, hours, and minutes) that the authentication token expires for this API user.
    Status
    The API user's status.
    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 Auth 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
CA Live API Creator
installation. The following example shows a URL if you are using the single-user demonstration package of
CA 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": "2014-07-21T12:41:42.546Z",    "lastLoginTs": "2014-07-19T08:37:15.049Z",    "lastLoginIP": "12.345.67.89"  }
 
The authentication token is obtained.
This authentication token is typically good for 24 hours. You can change the expiration value.
For more information about how to change the expiration value, see Auth Tokens.
Create an API User
Issue the following command, using the 
ident
 value for your API as the 
project_ident
 value:
You can 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 " + 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 in
CA Live API Creator
;
CA Live API Creator
 does not store API user passwords.
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    }
An API user is created
Change the API User's Password
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.
In this example command, the
newUser
object from the previous 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 }
 
Assign Roles to API Users
There is no limit to the number of roles you can assign to an API user. The list of roles you can assign to API users are those that have been added.
For more information about the list of predefined roles, and how to add new ones, see Role-Based Endpoint Access.
  1.  With your API open, in the Manage 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 you want to assign to the selected API user, and then save your changes.
The role is assigned to the API user.
Define Globals for API Users
Globals are variables that API Creator makes available to each transaction so that the transaction can determine what data the API user should have access to. For instance, you may 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.
For more information about globals, see Authorization.
  1. With your API open, in the Manage section, click 
    Users
    .
    The API Users page appears.
  2. Select the API user for which you want to assign a global.
  3. Click the 
    Globals
     tab.
  4. Enter comma-separated lists of values that apply only to the selected user.
    For example:
    deptNo=US Sales,[email protected]
The global is defined for the API user.