Version: 0.9.1 (beta)
Supported client libraries: jQuery, AngularJS, Python
Service connector constructor. Takes all options to connect to the service.
Parameter
User.token() to authenticate the user. Browser based applications
can also call User.signin() to retrieve the token as cookie to be handled automatically by the browser.See Endpoints for API calls for all supported options.
The services name is fix and cannot be changed. The ‘name’ parameter is not supported.
var user = new nive.User({token: 'security token'});
if(user.authenticated()).done(function(data, message, jqXHR) { user.name(); } );
// or
nive.User().name();
Retrieve a security token for the user. Either name or email or one of both allowed depending on identity policy. After obtaining the token it can be send in future requests to authenticate the user and perform secured actions.
Parameter
Return values
Status codes
nive.User().token({identity:'myname', password:'mypassword'})
.done(function (data, message, xhr) {
if(data.result) {
var token=result.token;
// use the token to get the current users name
nive.User(token).name();
}
});
POST http://mydomain.nive.io/users/api/token
Content-Type: application/json
Body: {"identity": "myname", "password": "mypassword"}
=>
Status 200 {"token": ""}
Signin the user with the credentials. Either name and/or email allowed depending on identity policy. This functions
automatically sets a cookie with the security token to be handled by the browser. Use User.token() to handle the
security token manually.
Parameter
Return values
Status codes
nive.User().signin({identity:'myname', password:'mypassword'})
.done(function (data, message, xhr) {
if(data.result) $('#message').text('You have been signed in!');
if(!data.result) $('#message').text('Failure: Please check your name and password!');
});
POST http://mydomain.nive.io/users/api/signin
Content-Type: application/json
Body: {"identity": "myname", "password": "mypassword"}
=>
Status 200 {"result": "true"}
Invalidates the authentication cookie and signs the user out.
Return values
nive.User().signout()
.done(function (data, message, xhr) {
$('#message').text('You have been signed out!');
});
http://mydomain.nive.io/users/api/signout
=>
{"result": "true"}
Returns the identity, unique id and name of the authenticated user. Use User.name() as alternative to retrieve a
reduced set of user identity information.
Return values
nive.User().identity()
.done(function (data, message, xhr) {
$('#name').text(data.realname || data.name);
});
GET http://mydomain.nive.io/users/api/identity
=>
{"name": "myname", "realname": "My Name", "email": "mymail@nive.co", "id": "cd345..."}
Returns the users name or email depending on identity policy. Use User.identity() to retrieve all the users
identity information.
Return values
nive.User().name()
.done(function (data, message, xhr) {
$('#name').text(data.realname || data.name);
});
GET http://mydomain.nive.io/users/api/name
=>
{"name": "myname", "realname": "My Name" }
Returns the profile values of the currently authenticated user.
Return values
nive.User().profile()
.done(function (data, message, xhr) {
$('#name').text(data.name);
$('#email').text(data.email);
});
GET http://mydomain.nive.io/users/api/profile
=>
{"name": "myname",
"email": "myemail@nive.co",
"realname": "My Name",
"data": "custom user data",
"activity": "2014/03/01 12:15:00",
"notify": "true",
"id": "da234553ed..."}
Check the authentication state of the current user. If no ‘groups’ are passed the function returns if the user is signed in. If ‘groups’ is not empty the function returns if the user is assigned to at least one the groups.
Parameter
Return values
Status codes
nive.User().authenticated({groups:'mygroup'})
.done(function (data, message, xhr) {
if(!data.result)
$('#message').text('You are not authenticated for mygroup');
});
GET http://mydomain.nive.io/users/api/authenticated?groups=mygroup
=>
{"result": false}
Checks whether or not the current user has the given permission(s).
Parameter
Return values
Status codes
nive.User().allowed({permission:'updateEmail'})
.done(function (data, message, xhr) {
if(!data.result)
$('#message').text('You are not allowed to update your email');
});
POST http://mydomain.nive.io/users/api/allowed
Content-Type: application/json
{"permission":"updateEmail"}
=>
{"result": false, "updateEmail": false}
Sign up a new user. The new user account is directly activated without verifying the email address or confirmation by the user adminstrator.
You can use the services permission settings in the backend to enable or disable the signup policy by allowing or removing the signupDirect permission.
Parameter
JSON.stringify(data)Return values
In case of a failure the functions returns a status message and a list of invalid form fields if any. Invalid fields are referenced by name.
[["name", "required"], ["password", "required"]]Status codes
nive.User().signupDirect({name:'myname', password:'mypassword', email:'myemail@nive.co'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('Done! Your account is ready to sign in.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/signupDirect
Content-Type: application/json
{"name":"myname", "password":"mypassword", "email":"myemail@nive.co"}
=>
{"result": "true"}
Sign up a new user. The new user account is initially inactive and has to be activted in a second step.
User.signupOptin() generates a token and sends it including a activation link to the email address of the new account.
The two required steps:
User.activate({token}) with the token as parameter.Requires the Activation page url field to be set in the user identity service administration backend. The activation
url will be passed to the email generator invoked by User.signupOptin().
You can use the services permission settings in the backend to enable or disable the signup policy by allowing or removing the signupOptin permission.
Parameter
JSON.stringify(data)Return values
In case of a failure the functions returns a status message and a list of invalid form fields if any. Invalid fields are referenced by name.
[["name", "required"], ["password", "required"]]Status codes
nive.User().signupOptin({name:'myname', password:'mypassword', email:'myemail@nive.co'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('Done! Check your email to complete the signup process.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/signupOptin
Content-Type: application/json
{"name":"myname", "password":"mypassword", "email":"myemail@nive.co"}
=>
{"result": "true"}
Sign up a new user. The new user account is initially inactive and has to be activted by the user administrator and optionally confirmed by email verification.
The required steps are:
User.review() with the
appropriate action. If action is set to ‘optin’ a confirmation mail is send to the users email address including
a activation token.User.activate({token}) with the token as parameter.See User.review() for details.
You can use the services permission settings in the backend to enable or disable the signup policy by allowing or removing the signupReview permission.
Parameter
JSON.stringify(data)Return values
In case of a failure the functions returns a status message and a list of invalid form fields if any. Invalid fields are referenced by name.
[["name", "required"], ["password", "required"]]Status codes
nive.User().signupReview({name:'myname',password:'mypassword',email:'myemail@nive.co'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('Done! Check your email to complete the signup process.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/signupReview
Content-Type: application/json
{"name":"myname", "password":"mypassword", "email":"myemail@nive.co"}
=>
{"result": "true"}
Sign up a new user. The new user account is initially activated but only accessible with the auto generated password send to the users email address.
You can use the services permission settings in the backend to enable or disable the signup policy by allowing or removing the signupSendpw permission.
Parameter
JSON.stringify(data)Return values
In case of a failure the functions returns a status message and a list of invalid form fields if any. Invalid fields are referenced by name.
[["name", "required"], ["password", "required"]]Status codes
nive.User().signupSendpw({name:'myname',email:'myemail@nive.co'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('Done! Your password has been send by email.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/signupSendpw
Content-Type: application/json
{"name":"myname", "email":"myemail@nive.co"}
=>
{"result": "true"}
Sign up a new user. This function generates a random and unique 30 byte user name. The generated name
is returned on success. If the identity policy is set to ‘name’ the email can be omitted and User.signupUid()
can easily be used to handle automated machine/device accounts.
The new account is instantly activated.
You can use the services permission settings in the backend to enable or disable the signup policy by allowing or removing the signupUid permission.
Parameter
JSON.stringify(data)Return values
In case of a failure the functions returns a status message and a list of invalid form fields if any. Invalid fields are referenced by name.
[["name", "required"], ["password", "required"]]Status codes
nive.User().signupUid({password:'mypassword'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('Done! Account is ready.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/signupUid
Content-Type: application/json
{"password":"mypassword"}
=>
{"result": "true"}
Activate a new account by calling this function with the activation token sent to the new users email address. This
function finally activates the users profile. The token is either generated by User.signupOptin() or User.review().
In general the token is passed as url parameter ‘token’ to the activation url. The activation url is configured in the backend or directly as part of the activation email template.
Parameter
Return values
Status codes
nive.User().activate({token:'some-unreadable-token'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('Hurra! You can sign in now.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/activate
Content-Type: application/json
{"token":"some-unreadable-token"}
=>
{"result": "true"}
Update a user profile with new values. Update can only be used for extended user data fields. To change one of ‘password’, ‘name’, ‘email’, ‘groups’ use one of the explicit functions.
Parameter
JSON.stringify(data)Return values
In case of a failure the functions returns a status message and a list of invalid form fields if any. Invalid fields are referenced by name.
[["data", "too long"]]Status codes
nive.User().update({realname: 'My Name',
notify: false,
data: JSON.stringify({custom: 'some value'})})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('Done! Profile updated.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/update
Content-Type: application/json
{"realname":"My Name", "notify":false, "data": {"custom": "some value"}}
=>
{"result": "true"}
Update a users password. Authenticated users can change their password directly by sending their current password and a new one.
Parameter
Return values
[["newpassword", "too short"]]Status codes
nive.User().updatePassword({password:'mypassword', newpassword:'secret'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('Done! Password updated.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/updatePassword
Content-Type: application/json
{"password":"mypassword", "newpassword":"secret"}
=>
{"result": "true"}
Update the users email address. Unlike User.verifyEmail() this function updates the email of the authenticated
user immediately without verification.
Parameter
Return values
[["email", "invalid_email"]]Status codes
nive.User().updateEmail({email:'mynewmail@nive.co'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('OK! Please check your email.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/updateMail
Content-Type: application/json
{"email":"mynewmail@nive.co"}
=>
{"result": "true"}
Change the email address of a user after verifying the new email in a second step. User.verifyEmail() generates a
token and sends it including a verification link to the new email address.
The two required steps:
User.verifyEmail2({token}) with the generated token as parameter.Requires the Email verification page url set in user identity service administration backend. The url will
be passed to the email generator invoked by User.verifyEmail().
Parameter
Return values
[["email", "invalid_email"]]Status codes
nive.User().verifyEmail({email:'mynewmail@nive.co'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('OK! Please check your email.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/verifyEmail
Content-Type: application/json
{"email":"mynewmail@nive.co"}
=>
{"result": "true"}
Activates the users new email address. The step requires the token generated and send to the users new email in
the first step by User.verifyEmail().
Parameter
Return values
Status codes
nive.User().verifyEmail2({token:'some-token'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('Done! Email activated.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/verifyEmail2
Content-Type: application/json
{"token":"some-token"}
=>
{"result": "true"}
Triggers a reset password mail including a token by entering the uses identity. The password can be updated in a second
step by calling User.resetPassword2({token, password}).
The two required steps:
User.resetPassword2({token, password}) with the generated token as parameter.Requires the Reset password page url set in user identity service administration backend. The url will
be passed to the email generator invoked by User.resetPassword().
Reset password can be used for not authenticated users if they have lost the password.
Parameter
Return values
Status codes
nive.User().resetPassword({identity:'myname'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('OK! Please check your email.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/resetPassword
Content-Type: application/json
{"identity":"myname"}
=>
{"result": "true"}
The second step of the password reset process for not authenticated users. The step requires the token generated and
send to the users email in the first step User.resetPassword().
In general the token is passed as url parameter ‘token’ to the reset password url. The url is configured in the backend or directly as part of the email template.
Parameter
Return values
Status codes
nive.User().resetPassword2({token:'some-token', newpassword:'secret'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('Done! Password updated.');
else
$('#message').text(data.messages);
});
POST http://mydomain.nive.io/users/api/resetPassword2
Content-Type: application/json
{"token":"some-token", "newpassword":"secret"}
=>
{"result": "true"}
Enables the authenticated user to send a messages to the user administrator. A message can have up to 5000 characters and is send to the admins email address.
Parameter
Return values
Status codes
nive.User().message()
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('OK! Done.');
else
$('#message').text('Something went wrong');
});
POST http://mydomain.nive.io/users/api/message
Content-Type: application/json
{"message": "Hello! I'm new here."}
=>
{"result": "true"}
Disables the currently signed in user by setting the users state to ‘false’. The user is
automatically signed out and prevented to sign in again. However the users data is not deleted or removed.
The user administrator can still access and reactive the user in the management backend at any later time.
To completely delete a user account use User.delete().
The users name and email are blocked and can not be used for new accounts.
Return values
nive.User().disable()
.done(function (data, message, xhr) {
if(data.result) $('#message').text('The user account has been disabled!');
});
DELETE http://mydomain.nive.io/users/api/disable
=>
{"result": false}
Deletes the currently signed in user by completely removing the users profile. After deletion the
account can not be restored again. User.delete() only affects data stored in the user database. Any other
data owned by the user stored in other services are not altered.
After deletion the user name and email can be used for new user accounts again. Use User.disable() instead
to make sure name and email can not be reused.
Return values
nive.User().delete()
.done(function (data, message, xhr) {
if(data.result) $('#message').text('The user account has been deleted!');
});
DELETE http://mydomain.nive.io/users/api/delete
=>
{"result": true}
Note
Administration function!
Process a pending user signup. You can either accept, accept with email verification, activate, reject or disable the user. If rejected the users profile will be removed.
Actions
The ‘optin’ action requires the Activation page url set in user identity service administration backend. The activation url will
be passed to the email generator invoked by User.review().
Parameter
Return values
Status codes
nive.User().review({identity: 'user1', action: 'accept'})
.done(function (data, message, xhr) {
if(data.result)
$('#message').text('OK! Done.');
else
$('#message').text('Something went wrong');
});
POST http://mydomain.nive.io/users/api/review
Content-Type: application/json
{"identity": "user1", "action": "accept"}
=>
{"result": "true"}
Note
Administration function!
Retrieve the users identity, data and state.
Parameter
Return values
Status codes
nive.User().getUser({identity:'user1'})
.done(function (data, message, xhr) {
if(data) {
$('#name').text(data.name);
// ...
}
});
POST http://mydomain.nive.io/users/api/getUser
Content-Type: application/json
{"identity": "user1"}
=>
{... profile values ...}
Note
Administration function!
Update the users profile values. Full access to the users values, state and security groups.
Parameter
Return values
Status codes
nive.User().setUser({identity:'user1', values: {active: false}})
.done(function (data, message, xhr) {
if(data.result) $('#message').text('The users profile has been updated!');
});
POST http://mydomain.nive.io/users/api/setUser
Content-Type: application/json
{"identity": "user1", "values": {"active": "false"}}
=>
{"result": true}
Note
Administration function!
Deletes the user by completely removing the users profile. After deletion the account can not be restored again. This only affects data stored in the user database. Any other data owned by the user stored in other services are not altered.
After deletion the user name and email can be used for new user accounts again. Use User.setUser() with active
set to ‘false’ instead to make sure name and email can not be reused.
Parameter
Return values
Status codes
nive.User().removeUser({identity: 'user1'})
.done(function (data, message, xhr) {
if(data.result) $('#message').text('The user account has been deleted!');
});
POST http://mydomain.nive.io/users/api/removeUser
Content-Type: application/json
{"identity": "user1"}
=>
{"result": true}
Note
Administration function
Lists user profiles by a variety of search parameters. See also User.identities().
Parameter
Return values
Status codes
nive.User().list({"pending": true})
.done(function (data, message, xhr) {
if(data.size) $('#message').text('Pending user reviews found!');
});
POST http://mydomain.nive.io/users/api/list
Content-Type: application/json
{"active": true}
=>
{"users": [...], "start": 1, size: 1}
Note
Administration function!
Lists user identities by a variety of search parameters. See also User.list().
Parameter
Return values
Status codes
nive.User().identities({"pending": true})
.done(function (data, message, xhr) {
if(data.size) $('#message').text('Pending user reviews found!');
});
POST http://mydomain.nive.io/users/api/identities
Content-Type: application/json
{"active": true}
=>
{"users": [...], "start": 1, size: 1}
Note
Administration function!
Retrieve all permissions and assigned groups of this service. The result contains a list of permission and groups items.
[
{permission: "signupDirect", groups: ["sys:noone"]},
{permission: "signupReview", groups: ["sys:everyone"]},
...
]
Return values
The function returns a permission:name, groups:list item for each permission. [{permission:name, groups:list}, ...]
Status codes
---
---
Note
Administration function!
Update a single or multiple service permissions. Each permission to be updated must include the name, one or multiple groups and a action: ‘add’ (default), ‘replace’, ‘revoke’.
[
{permission: "signupDirect", groups: ["sys:noone"], action: "replace"},
{permission: "signupReview", groups: ["sys:everyone"], action: "revoke"},
...
]
Parameter
for each permission
Return values
Status codes
---
---
Simple test and health check function.
Parameter
Return values
nive.User().ping()
.done(function (data, message, xhr) {
$('#message').text('Seems alive!');
});
GET http://mydomain.nive.io/users/api/ping
Content-Type: application/json
{"active": true}
=>
{"result": 1}