Application Users

Each EVRYTHNG application can create individual Application Users that are scoped to just that application. Application Users represent and authorize the users of such web or native applications. Each of these have their own personal details and login credentials, and are designed to serve as an access to only those resources (products, Thngs, etc.) that the user is to be concerned with. Each Application User is granted an Application User API Key when they are created, as well as on each subsequent log in. This key is revoked if and when an Application User logs out or is deleted.

For example, a commercial traceability app might create an Application User for each of the staff members that interact with the traceability solution, and can then use their own API key to create actions or access other resources to carry out their job, usually through the app's UI. Using each Application User API Key, the traceability actions are created by the staff members themselves.

In addition to named Application Users, an application may also create anonymous Application Users, which are not intended to be uniquely identified, but exist purely to allow a user-level access to resources in a temporary fashion or to perform a once-only action, and do not need to persist for any given length of time. For example, a single scan of an on-pack QR code would use an anonymous user to allow a more detailed action record to be created.

API Status General Availability: /accesses /accesses/:accessId /auth/evrythng /auth/evrythng/facebook /auth/evrythng/users /users /users/:evrythngUser

ApplicationUserDocument Data Model

See also: BirthdayDocument, ScopesDocument, ApplicationUserAccessDocument

Filterable Fields

This resource type can be filtered using the following fields and operators.

BirthdayDocument Data Model

ApplicationUserAccessDocument Data Model

Create an Application User

❗Note

This endpoint creates an unactivated user. Use the /auth/evrythng/users/:evrythngUser/validate endpoint to finish the creation process once the user has confirmed their email address etc. \n\nSee the Activate an Application User page for more information.

Create a new unactivated Application User, using the Application API Key. The email must be a unique identifier within the app, therefore your application will not be able to create more than one user with the same email address.

If the user doesn't exist yet, the platform will create a new user and return an activationCode in the response. Before the user gets activated and can access data in the API, the application will need to send back the activation code to our API for that user as shown below. This additional step allows the client application to ensure that the email provided has been validated to be real and accessible by the user.

Activate an Application User

Once an Application User resource has been created with the /auth/evrythng/users endpoint, it needs to be activated (by the client application) by sending a POST request including the activationCode. This step allows a confirmation email or other challenge to be issued in the application's user experience to verify their identify before they are allowed full access to the application and its resources.

If the activationCode is correct, the user will be activated and authenticated, and the Application User will be assigned an Application User API Key.

If you forget the activationCode between creating the Application User and activation, you can retrieve it using a GET request to the /users/:evrythngUser/status endpoint.

Read all Application Users

Read all available Application Users using the Trusted Application API Key or the Operator API Key. The result may be paginated if there are more than 30 items.

Read an Application User

Update an Application User

Authorised Application Users can modify their own data (including the password) using their Application User API key. An Operator is also allowed to update data of users registered within their accounts.

Update an Application User's Password

An Application User can update the password they use to log into an application using a PUT request. However, they must also provide their current password as a form of verification.

Delete an Application User

Delete an Application User by ID. This action cannot be undone.

Create an Anonymous User

Create an anonymous user that does not need to be activated by including the ?anonymous=true parameter in the query parameters and body of the request. This type of user exists to enable a temporary or anonymous access. This kind of user is useful for tracking devices not pre-associated with a user, but can be updated with additional user information at a later time if needed.

Log a User In

Authenticate (log in) an existing user with their email and password used at registration time. Apps can authenticate existing users using the pair email + password and receiving an Application User API key. The request is made with an ApplicationUserLoginDocument.

If the user is active and if the credentials are correct, the platform will then return a new Application User API key which can be used until the user is logged out.

Log a User In with Access Info

Similar to the standard login process, an Application API Key can log a user in and receive access information about that user at the same time. If the actor and user have the same value, the user is authenticating themselves. If these values differ, the actor is logging in on behalf of the user.

In this case, the email property in the request payload can be replaced with the evrythngUser ID, if known.

ApplicationUserLoginDocument Data Model

Create/Authenticate a User via Facebook

EVRYTHNG applications can also sign up and login users using their accounts on external services, such as Facebook.

In practice, apps must log in users via Facebook and then create a user account on EVRYTHNG that is bound to his Facebook account. This is done by posting the user's Facebook access token on the /auth/facebook endpoint, using the Application API Key.

When creating a new user, the platform will send the access token to Facebook to validate the user has been created by the correct Facebook application (the access token corresponds to the appId of the Facebook object in the corresponding application).

❗Important

The EVRYTHNG Platform uses the provided Facebook token to retrieve information about the user. But some of this user data is only visible if the corresponding permissions have been requested upon authenticating the user through the Facebook API.\n\nIn order to allow the user to be created properly you must ask for at least the email and user_birthday permissions.

See also: FacebookAccessDocument

See also: FacebookAccessDocument

FacebookAccessDocument Data Model

See also: FacebookAccessParametersDocument

FacebookAccessParametersDocument Data Model

Authenticate a User via Facebook with Evrythng.js

The following login calls open a generic Facebook login popup. Once authenticated with Facebook you're also authenticated with EVRYTHNG.

First, make sure the application has the correct socialNetworks metadata set. An example is shown below:

In the app itself, log in using the Facebook default permissions (email only):

Alternatively, using custom permissions (be sure to have them enabled in your Facebook Application first):

Read more about Facebook login permissions and connection status in the Facebook API reference.

Log the User Out

User access token can be invalidated by using it to call to /auth/all/logout regardless of the method the user authenticated with (EVRYTHNG or 3rd party). The user's API key will become invalid after the call.

The platform acknowledges the logout operation in the response body.

Share Access with Other Users

An Application User can share limited access to their scoped resources with another existing Application User. This works by assigning an existing Application User role to the email address belonging to the second Application User.

Once the second user has been given an access, they will be able to use a new API key available to them to view and modify resources belonging to the granting user's account, according to the shared role's permissions.

❗Notes

• The role being assigned must be in scope of the authenticating Application User's role, and also must be in the same project scope.\n\n* If the role being assigned to a secondary user is the same as the authenticating Application User's role, then it must be in scope of itself.

Jump To ↓

Create an Access Read all Available Accesses Delete an Access

Create an Access

Create a new Application User access for another Application User by specifying their email address and role to be assigned.

In the response, user is the ID of the Application User granting the new access, and actor is the ID of the receiving Application User.

Read all Available Accesses

An Application User can read all the available accesses (including API keys) they have been given. By default they will have at least one - their own application access. Any additional accesses created for them using the process described above will also appear here.

For any access, actor is the ID of the assigned Application User, and user is the ID of the Application User that granted the access.

Delete an Access

Either the granting or receiving Application User can revoke the access with a DELETE request. After this is done, the granting user must create a new access before the receiving user can access the granting user's resources again.