ActivateAuthenticateAmplify
DashboardSupportDeveloper Blog

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

Jump To ↓

ApplicationUserDocument Data Model
Create an Application User
Activate an Application User
Read all Application Users
Read an Application User
Update an Application User
Delete an Application User
Create an Anonymous User
Log a User In
Log a User In with Access Info
Create/Authenticate a User via Facebook
Log the User Out
Share Access with Other Users

ApplicationUserDocument Data Model

.id (string, read-only)
    The ID of this resource.

.email (string, required)
    E-mail address of the user. Unique within the app.

.firstName (string, required)
    User's first name.

.lastName (string, required)
    User's last name.

.password (string, required)
    The user's password.

.birthday (BirthdayDocument)
    An Application User's birthday.

.gender (string, one of 'male', 'female')
    User's gender.

.timezone (string)
    The current timezone for the user. For example: 
    `Pacific/Honolulu` or `Europe/Uzhgorod`).

.locale (string)
    The default language tag for the user, complied with RFC 
    5646.

.photo (string)
    URL of the user's photo.

.customFields (CustomFieldsDocument)
    Object of case-sensititve key-value pairs of custom fields 
    associated with the resource.

.tags (array of string)
    Array of string tags associated with this resource.

.project (string, read-only)
    The project ID of the application this user belongs to.

.app (string, read-only)
    The ID of the application this user belongs to.

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.access (ApplicationUserAccessDocument)
    Object containing data relevant to an Application User's 
    platform access.

.scopes (ScopesDocument)
    Project and user scopes arrays.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object describing an Application User.",
  "required": ["firstName", "lastName", "email", "password"],
  "properties": {
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "email": {
      "type": "string",
      "description": "E-mail address of the user. Unique within the app."
    },
    "firstName": {
      "type": "string",
      "description": "User's first name."
    },
    "lastName": {
      "type": "string",
      "description": "User's last name."
    },
    "password": {
      "type": "string",
      "description": "The user's password.",
      "minLength": 8,
      "maxLength": 30
    },
    "birthday": {
      "additionalProperties": false,
      "type": "object",
      "description": "An Application User's birthday.",
      "required": ["day", "month", "year"],
      "properties": {
        "day": {
          "type": "integer",
          "description": "The day of the birthday.",
          "example": 1,
          "minimum": 1,
          "maximum": 31
        },
        "month": {
          "type": "integer",
          "description": "The month of the birthday.",
          "example": 12,
          "minimum": 1,
          "maximum": 12
        },
        "year": {
          "type": "integer",
          "description": "The year of the birthday.",
          "example": 2018,
          "minimum": 1900
        }
      }
    },
    "gender": {
      "type": "string",
      "description": "User's gender.",
      "enum": ["male", "female"]
    },
    "timezone": {
      "type": "string",
      "description": "The current timezone for the user. For example: `Pacific/Honolulu` or `Europe/Uzhgorod`)."
    },
    "locale": {
      "type": "string",
      "description": "The default language tag for the user, complied with RFC 5646."
    },
    "photo": {
      "type": "string",
      "description": "URL of the user's photo."
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "project": {
      "type": "string",
      "description": "The project ID of the application this user belongs to.",
      "readOnly": true,
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
    },
    "app": {
      "type": "string",
      "description": "The ID of the application this user belongs to.",
      "readOnly": true,
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
    },
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "access": {
      "additionalProperties": false,
      "type": "object",
      "description": "Object containing data relevant to an Application User's platform access.",
      "properties": {
        "id": {
          "type": "string",
          "description": "The access ID.",
          "readOnly": true
        },
        "project": {
          "type": "string",
          "description": "The ID of the project the user belongs to.",
          "readOnly": true
        },
        "app": {
          "type": "string",
          "description": "The ID of the application the user belongs to.",
          "readOnly": true
        },
        "user": {
          "type": "string",
          "description": "This user's ID.",
          "readOnly": true
        },
        "actor": {
          "type": "string",
          "description": "The accessing actor's ID.",
          "readOnly": true
        },
        "role": {
          "type": "string",
          "description": "The ID of the user's role.",
          "readOnly": true
        },
        "apiKey": {
          "type": "string",
          "description": "The actor's Application User API Key.",
          "readOnly": true
        },
        "customFields": {
          "type": "object",
          "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
        }
      }
    },
    "scopes": {
      "additionalProperties": false,
      "type": "object",
      "description": "Project and user scopes arrays.",
      "required": ["users", "projects"],
      "properties": {
        "users": {
          "type": "array",
          "description": "An array of Application User IDs this resource is scoped to.",
          "items": { "type": "string" }
        },
        "projects": {
          "type": "array",
          "description": "An array of project IDs this resource is scoped to.",
          "items": {
            "type": "string",
            "description": "The ID of this resource.",
            "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
            "readOnly": true
          }
        }
      }
    }
  },
  "x-filterable-fields": ["email", "firstName", "lastName"]
}

{
  "id": "UnaP5scsfcQ4tQwaRXEyheBd",
  "createdAt": 1510915630522,
  "tags": [
    "example",
    "user"
  ],
  "updatedAt": 1510915657700,
  "email": "[email protected]",
  "firstName": "Mike",
  "lastName": "Smith",
  "timezone": "Europe/London",
  "locale": "en-gb",
  "photo": "https://upload.wikimedia.org/wikipedia/commons/8/84/Example.svg",
  "birthday": {
    "day": 19,
    "month": 12,
    "year": 1992
  },
  "gender": "male",
  "project": "UmxHK6K8BXsa9KawRh4bTbqc",
  "app": "U3pxRQh2eD8RtKwaRgerfQgc"
}

See also: BirthdayDocument, ScopesDocument, ApplicationUserAccessDocument

Filterable Fields

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

FieldTypeOperators
emailString=
firstNameString=
lastNameString=

BirthdayDocument Data Model

.day (integer, required)
    The day of the birthday.

.month (integer, required)
    The month of the birthday.

.year (integer, required)
    The year of the birthday.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An Application User's birthday.",
  "required": ["day", "month", "year"],
  "properties": {
    "day": {
      "type": "integer",
      "description": "The day of the birthday.",
      "example": 1,
      "minimum": 1,
      "maximum": 31
    },
    "month": {
      "type": "integer",
      "description": "The month of the birthday.",
      "example": 12,
      "minimum": 1,
      "maximum": 12
    },
    "year": {
      "type": "integer",
      "description": "The year of the birthday.",
      "example": 2018,
      "minimum": 1900
    }
  }
}

ApplicationUserAccessDocument Data Model

.id (string, read-only)
    The access ID.

.project (string, read-only)
    The ID of the project the user belongs to.

.app (string, read-only)
    The ID of the application the user belongs to.

.user (string, read-only)
    This user's ID.

.actor (string, read-only)
    The accessing actor's ID.

.role (string, read-only)
    The ID of the user's role.

.apiKey (string, read-only)
    The actor's Application User API Key.

.customFields (object)
    Object of case-sensititve key-value pairs of custom fields 
    associated with the resource.

{
  "type": "object",
  "description": "Object containing data relevant to an Application User's platform access.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The access ID.",
      "readOnly": true
    },
    "project": {
      "type": "string",
      "description": "The ID of the project the user belongs to.",
      "readOnly": true
    },
    "app": {
      "type": "string",
      "description": "The ID of the application the user belongs to.",
      "readOnly": true
    },
    "user": {
      "type": "string",
      "description": "This user's ID.",
      "readOnly": true
    },
    "actor": {
      "type": "string",
      "description": "The accessing actor's ID.",
      "readOnly": true
    },
    "role": {
      "type": "string",
      "description": "The ID of the user's role.",
      "readOnly": true
    },
    "apiKey": {
      "type": "string",
      "description": "The actor's Application User API Key.",
      "readOnly": true
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    }
  }
}

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.

See 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.

POST /auth/evrythng/users
Content-Type: application/json
Authorization: $APPLICATION_API_KEY

ApplicationUserDocument

curl -i -H "Content-type: application/json" \
  -H "Authorization: $APPLICATION_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/auth/evrythng/users' \
  -d '{ 
    "firstName": "Mike", 
    "lastName": "Smith", 
    "email": "[email protected]", 
    "password": "password" 
  }'

const payload = {
  email: '[email protected]',
  password: 'mypa5w0rd',
  firstName: 'Ivan',
  lastName: 'Cherepanov',
  customFields: {
    catchphrase: 'crzht no blockers crzht',
  }
};

app.appUser().create(payload)
  .then(console.log);

ApiManager appApiManager = new ApiManager(APPLICATION_API_KEY);

User user = new User();
user.setEmail("[email protected]");
user.setPassword("password");
user.setFirstName("Example First Name");
user.setLastName("Example Last Name");

Credentials creds = apiManager.authService().evrythngUserCreator(user).execute();
System.out.println("evrythngUser=" + creds.getEvrythngUser());
System.out.println("activationCode=" + creds.getActivationCode());

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "evrythngUser": "UmVxeKVQeg8wQ5waaXsrda2t",
  "activationCode": "3RwaN5LQ",
  "status": "inactive",
  "email": "[email protected]"
}

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.

POST /auth/evrythng/users/:evrythngUser/validate
Content-Type: application/json
Authorization: $APPLICATION_API_KEY

{
  "activationCode": String
}

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $APPLICATION_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/auth/evrythng/users/:evrythngUser/validate' \
  -d '{ 
    "activationCode": "348s83j" 
  }'

const payload = {
  email: '[email protected]',
  password: 's0m3p455w0rd736!3', 
  firstName: 'Mike',
  lastName: 'Smith',
};

// Create and validate in one step!
app.appUser().create(payload)
  .then(res => res.validate())
  .then(newUser => console.log('Validated!'));

// Or, validate a previously created user
otherUser.validate().then((validated) => {
  console.log(`Validated app user: ${validated}`);
});

// Credentials from a previous invokation of evrythngUserCreator()
creds = apiManager.authService().evrythngUserValidator(creds.getEvrythngUser(), creds.getActivationCode()).execute();
System.out.println("status=" + creds.getStatus());

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "status": "active",
  "evrythngUser": "UmVxeKVQeg8wQ5waaXsrda2t",
  "evrythngApiKey": "AGCSBhdt07tnLxtObxqObpOI91234S4KBfot9T5oi..."
}

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.

GET /users
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/users'

operator.user().read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "UmVxeKVQeg8wQ5waaXsrda2t",
    "createdAt": 1497451343302,
    "updatedAt": 1497451406584,
    "email": "[email protected]",
    "firstName": "Mike",
    "lastName": "Smith",
    "project": "UmxHK6K8BXsa9KawRh4bTbqc",
    "app": "Umbn56MmBDsatpaawg6XgKfk"
  }
]

Read an Application User

GET /users/:userId
Authorization: $OPERATOR_API_KEY

curl -i -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/users/UGN5FtfdV6PNQ7aRaXwCrhHp'

const userId = 'UGN5FtfdV6PNQ7aRaXwCrhHp';

operator.user(userId).read()
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "UGN5FtfdV6PNQ7aRaXwCrhHp",
  "createdAt": 1507561299992,
  "updatedAt": 1507561300298,
  "email": "[email protected]",
  "firstName": "Bora",
  "lastName": "Horza",
  "project": "UmrK2QWAegPwQ5waRh4QMQfp",
  "app": "UGr5kQCUBMsr9NwwR2wPeKbe"
}

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.

PUT /users/:evrythngUser
Authorization: $OPERATOR_API_KEY
Content-Type: application/json

ApplicationUserDocument (subset)

curl -i -H "Content-type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://$EVT_API_DOMAIN/users/UYtUFbWKRq9wDCd5qEdmccyp' \
  -d '{ 
    "firstName": "James" 
  }'

var payload = { firstName: 'James' };

// User scope can update itself
user.update(payload).then(console.log);

// Operator can also update a user on its behalf
operator.user(userId).update(payload)
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "UYtUFbWKRq9wDCd5qEdmccyp",
  "createdAt": 1494924625617,
  "updatedAt": 1497451913694,
  "email": "[email protected]",
  "firstName": "James",
  "lastName": "Smith",
  "project": "UmxHK6K8BXsa9KawRh4bTbqc",
  "app": "Umbn56MmBDsatpaawg6XgKfk"
}

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.

PUT /users/:evrythngUser
Content-Type: application/json
Authorization: $APPLICATION_USER_API_KEY

{
  "password": "M7@29P6Stk9zF5gX5@4!c3Vm",
  "oldPassword": "0ldp455w0rd"
}

curl -H "Content-Type: application/json" \
  -H "Authorization: $APPLICATION_API_KEY" \
  -X PUT 'https://$EVT_API_DOMAIN/users/UmQ6dEBKMG8YEMaRah3FVf3f' \
  -d '{
    "password": "M7@29P6Stk9zF5gX5@4!c3Vm",
    "oldPassword": "0ldp455w0rd"
  }'

const userId = 'UmQ6dEBKMG8YEMaRah3FVf3f';
const payload = {
  password: 'M7@29P6Stk9zF5gX5@4!c3Vm',
  oldPassword: '0ldp455w0rd',
};

operator.user(userId).update(payload)
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "UmQ6dEBKMG8YEMaRah3FVf3f",
  "createdAt": 1509701451010,
  "updatedAt": 1509701489615,
  "email": "[email protected]",
  "firstName": "Mike",
  "lastName": "Smith",
  "project": "UmQMUhSFqm8hYMaawhmkBChr",
  "app": "U3QMUhTn6GPEhMwawE32Bfkr"
}

Delete an Application User

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

DELETE /users/:evrythngUser
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://$EVT_API_DOMAIN/users/UYtUFbWKRq9wDCd5qEdmccyp'

const userId = 'UYtUFbWKRq9wDCd5qEdmccyp';

operator.user(userId).delete();

HTTP/1.1 200 OK

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.

POST /auth/evrythng/users?anonymous=true
Content-Type: application/json
Authorization: $APPLICATION_API_KEY

{
  "anonymous": true
}

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $APPLICATION_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/auth/evrythng/users?anonymous=true' \
  -d '{ 
    "anonymous": true 
  }'

const payload = { anonymous: true };

// Create the user and store the returned credentials
app.appUser().create(payload)
  .then((anonUser) => {
    // Returns a ready to use User scope that doesn't need validation
    console.log(`Created anonymous user: ${anonUser.id}`);

    // Store anonymous user details locally
    if (window.localStorage) {
      localStorage.apiKey = anonUser.apiKey;
    }
  });

// Next time, load the user from localstorage
const anonUser = new evrythng.User(localStorage.apiKey);

User user = new User();
Credentials creds = apiManager.authService().evrythngUserCreator(user).queryParam("anonymous", "true").execute();
System.out.println("Anonymous ID: " + creds.getEvrythngUser());
System.out.println("Anonymous API key: " + creds.getEvrythngApiKey());

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "evrythngUser": "U3BSenB6Bg8w9pRawk5ycwdt",
  "status": "anonymous",
  "email": "anon-12d855f0-510f-11e7-bc07-0bd000cf37af.app-umbn56mmbdsatpaawg55gkfk@anon.evrythng.com",
  "evrythngApiKey": "Tw9Tw6M4s0ip5k12Pi2xd4VpcliT0H41tW912343X07Z...",
  "socialNetwork": "evrythng"
}

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.

POST /auth/evrythng
Content-Type: application/json
Authorization: $APPLICATION_API_KEY

ApplicationUserLoginDocument

curl -i -H "Content-type: application/json" \
  -H "Authorization: $APPLICATION_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/auth/evrythng' \
  -d '{ 
    "email": "[email protected]", 
    "password": "s0mepassw0rd" 
  }'

const payload = {
  email: '[email protected]',
  password: 's0mepassw0rd',
};

// Login user (with EVRYTHNG Auth) and create user scope
app.login(payload)
  .then(console.log);

Credentials creds = new Credentials(email, password);
creds = appApiManager.authService().evrythngUserAuthenticator(creds).execute();
System.out.println("User ID: " + creds.getEvrythngUser());
System.out.println("User API key: " + creds.getEvrythngApiKey());

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "socialNetwork": "evrythng",
  "evrythngUser": "U3BSenB6Bg8w9pRawk5ycwdt",
  "evrythngApiKey": "cYFWnAiRTaNeOnj8ejc0qQg9Fg4wyPDV4U31sB2j...",
  "email": "[email protected]"
}

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.

POST /users/login
Content-Type: application/json
Authorization: $APPLICATION_API_KEY

ApplicationUserLoginDocument

curl -H "Content-Type: application/json" \
  -H "Authorization: $APPLICATION_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/users/login' \
  -d '{
    "email": "[email protected]",
    "password": "s0omepassw0rd"
  }'

const payload = {
  email: '[email protected]',
  password: 's0mepassw0rd'
};

app.login(payload).then(console.log);

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "UmW8bewpVD8RQKRaR2qpDtyh",
  "createdAt": 1499337739424,
  "updatedAt": 1499337754551,
  "email": "[email protected]",
  "firstName": "Mike",
  "lastName": "Smith",
  "project": "UGBNTUbf6tQVhswwagmfVrcm",
  "app": "U3fdqbMpqt9VhsaRwED3xmtn",
  "access": {
    "id": "595e141ab4a46a2c00b7bdf1",
    "project": "UGBNTUbf6tQVhswwagmfVrcm",
    "app": "U3fdqbMpqt9VhsaRwED3xmtn",
    "user": "UmW8bewpVD8RQKRaR2qpDtyh",
    "actor": "UmW8bewpVD8RQKRaR2qpDtyh",
    "role": "base_app_user",
    "apiKey": "Lz5RtLxwDP3kS6VawbK..."
  }
}

ApplicationUserLoginDocument Data Model

.email (string)
    The email address assigned to the Application User.

.password (string)
    The Application User's password used at account creation 
    time.

{
  "type": "object",
  "description": "An object representing an Application User login request.",
  "properties": {
    "email": {
      "type": "string",
      "description": "The email address assigned to the Application User."
    },
    "password": {
      "type": "string",
      "description": "The Application User's password used at account creation time."
    }
  }
}

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.

In order to allow the user to be created properly you must ask for at least the email and user_birthday permissions.

POST /auth/facebook
Content-Type: application/json
Authorization: $APPLICATION_API_KEY

FacebookAccessDocument (only 'access' property)

See also: FacebookAccessDocument

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "evrythngApp": "Up9TM4MAFbVaHtaRaFNGCAbg",
  "socialNetwork": "facebook",
  "socialNetworkId": "10217387694263999",
  "access": {
    "token": "EAAVwFgKCeqABABB..."
  },
  "appId": "1530614717250208",
  "evrythngUser": "UKQTMpMA7bFx6kwaRmkdVapm",
  "evrythngApiKey": "PV2XvlPMpW4uAwld..."
}

See also: FacebookAccessDocument

FacebookAccessDocument Data Model

.socialNetwork (string, one of 'facebook')
    The social network type

.access (FacebookAccessParametersDocument)
    An object representing an access to Facebook.

.socialNetworkId (string)
    The ID of the user on Facebook

.appId (string)
    The ID of the application

.evrythngUser (string)
    The ID of the App User

.evrythngApiKey (string)
    The API key of the App User

{
  "type": "object",
  "description": "An object representing an access to Facebook.",
  "properties": {
    "socialNetwork": {
      "type": "string",
      "description": "The social network type",
      "enum": [ "facebook" ]
    },
    "access": {
      "type": "object",
      "description": "An object representing an access to Facebook.",
      "properties": {
        "expires": {
          "type": "number",
          "description": "Timestamp when the access expires"
        },
        "token": {
          "type": "string",
          "description": "The Facebook access token"
        }
      }
    },
    "socialNetworkId": {
      "type": "string",
      "description": "The ID of the user on Facebook"
    },
    "appId": {
      "type": "string",
      "description": "The ID of the application"
    },
    "evrythngUser": {
      "type": "string",
      "description": "The ID of the App User"
    },
    "evrythngApiKey": {
      "type": "string",
      "description": "The API key of the App User"
    }
  }
}

{
  "evrythngApp": "Up9TM4MAFbVaHtaRaFNGCAbg",
  "socialNetwork": "facebook",
  "socialNetworkId": "10217387694263999",
  "access": {
    "token": "EAAVwFgKCeqABABB..."
  },
  "appId": "1530614717250208",
  "evrythngUser": "UKQTMpMA7bFx6kwaRmkdVapm",
  "evrythngApiKey": "PV2XvlPMpW4uAwld..."
}

See also: FacebookAccessParametersDocument

FacebookAccessParametersDocument Data Model

.expires (number)
    Timestamp when the access expires

.token (string)
    The Facebook access token

{
  "type": "object",
  "description": "An object representing an access to Facebook.",
  "properties": {
    "expires": {
      "type": "number",
      "description": "Timestamp when the access expires"
    },
    "token": {
      "type": "string",
      "description": "The Facebook access token"
    }
  }
}

Authenticate a User via Facebook with Evrythng.js

🚧

Note

evrythng.js asynchronously loads the Facebook Javascript SDK for you. You do not need to authenticate with Facebook another way.

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:

{
  "id": "Up9TM4MAFbVaHtaRaFNGCAbg",
  "createdAt": 1542638275717,
  "updatedAt": 1542638459365,
  "name": "FacebookTestUser",
  "socialNetworks": {
    "facebook": {
      "appId": "1530614717250999",
      "appSecret": "b6bfdd04..."
    }
  },
  "appApiKey": "K4FVCos6c6UyyQyu...",
  "defaultRole": "base_app_user"
}

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

// Ensure app.socialNetworks.facebook is set with ID and token first
const app = new evrythng.Application({
  apiKey: APPLICATION_API_KEY,
  facebook: true,
});

// Show the pop up for login, to be filled by the user
app.login('facebook').then((response) => {
  const fbStatus = response.status;
  const user = response.user;
});

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

// Show the pop up for login, to be filled by the user
app.login('facebook', { 
  scope: 'email,user_birthday' 
}).then((response) => {
  const fbStatus = response.status;
  const user = response.user;

  // Now every call using user will use their Application User API Key
});

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.

POST /auth/all/logout
Content-Type: application/json
Authorization: $APPLICATION_USER_API_KEY

curl -i -H "Content-type: application/json" \
  -H "Authorization: $APPLICATION_USER_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/auth/all/logout'

// From a pre-existing User scope
user.logout();

// creds obtained from a previous invokation of evrythngUserAuthenticator()
apiManager.authService().authLogouter().apiKey(creds.getEvrythngApiKey()).execute();

The platform acknowledges the logout operation in the response body.

HTTP/1.1 201 CREATED
Content-Type: application/json

{
  "logout": "ok"
}

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.

  • 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.

POST /accesses
Content-Type: application/json
Authorization: $APPLICATION_USER_API_KEY

{
  "email": "[email protected]",
  "role": "59a676cc6404572c00294433"
}

curl -H "Content-Type: application/json" \
  -H "Authorization: $APPLICATION_USER_API_KEY" \
  -X POST 'https://$EVT_API_DOMAIN/accesses' \
  -d '{
    "email": "[email protected]",
    "role": "59a676cc6404572c00294433"
  }'

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "59ad60d9b24413002c7d7695",
  "project": "UG4WExTKBqPr9NwRa3twYDnk",
  "app": "UG4NWfQ7BMPN97wawGQRrxtm",
  "user": "UGHrfg5XB6PNQraaamtRNbts",
  "actor": "UGH7CG5WeqP7tNRawGQwrydc",
  "role": "59a676cc6404572c00294433"
}

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.

GET /accesses
Authorization: $APPLICATION_USER_API_KEY

curl -H "Authorization: $APPLICATION_USER_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/accesses'

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "5a05acfa9bc1420031fa786d",
    "project": "UnRCn5syM3shYqaawYDn4bbs",
    "app": "UnaCn5P3MmshEMRwaED4nbyd",
    "user": "UHaf46PWMGPYE6wRwhDHnbVd",
    "actor": "UHaf46PWMGPYE6wRwhDHnbVd",
    "apiKey": "QW3W8iIjBZfdIIdI7Ik3FHxKPJbLMj3jfwTCxoUmp..."
  },
  {
    "id": "5a05ad909bc1420031fa7874",
    "project": "UnRCn5syM3shYqaawYDn4bbs",
    "app": "UnaCn5P3MmshEMRwaED4nbyd",
    "user": "U4wCHMDDMGPYEMawREg4Hxdb",
    "actor": "UHaf46PWMGPYE6wRwhDHnbVd",
    "role": "5a05ac349bc1420031fa7860",
    "customFields": {
      "email": "[email protected]"
    },
    "apiKey": "L4PDu9RUMvFttmsiYV8ASUG5nxInAQPItHICNSkCq..."
  }
]

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.

DELETE /accesses/:accessId
Authorization: $APPLICATION_USER_API_KEY

curl -H "Authorization: $APPLICATION_USER_API_KEY" \
  -X DELETE 'https://$EVT_API_DOMAIN/accesses/59afba76dff5ea002c88c4e9'

HTTP/1.1 204 No Content