Key Concepts

Login/User Authentication

Knodes authenticates two things:

  1. The customer, using the credentials on every call (customer_id and customer_secret)

  2. That the customer has been granted access to a user’s network data, using the network access credentials provided during users/connect, combined with the customer’s network application credentials. Knodes can contact the network as the customer, and thus can verify that the customer really does have access to the user.

In practice, that means that customer clients must implement network-based authentication on the client side at least once (to capture the initial authorization and network access credentials). At the customer’s discretion, they may continue to use network-based authentication as their main login mechanism going forward, or they may choose to maintain their own user model that they map to Knodes’ user identifiers that they use after the initial authorization.

For performance reasons, we do ask that customers call either users/connect or users/notify_active when a user becomes active after a long period of inactivity, but that is not truly an authentication hook, see “Sessions/State” below.


The API is stateless. Assuming the customer is already registered, and has connected with a particular user, the customer may make any user-related calls at any time. Due to performance reasons we do ask that you call either users/connect or users/notify_ active when a user has become active after a long period of inactivity. This will help us to ensure that a user’s data is fully loaded and ready to query for the subsequent user session.

Which of these calls you use at the outset of a user session is at your discretion. Calls to users/connect when the user is already connected perform exactly the same as a call to users/notify_active. If your application uses network-based authentication for all user logins, it is probably simplest to call users/connect each time, since that way registration and login have the same code path.

Network vs Knodes Identity

Much of the data returned by Knodes maps to data returned by the user’s connected network(s). In particular, each Person object maps to one or more network entities, and each Document object maps to exactly one network entity.

Generally, Knodes provides a sub-set of the network data, often cleaned up and normalized into a unified data model. All calls that return data that correlates to network data accept an optional include_network_data parameter. If set, the response will include a network_data field that contains escaped JSON for the raw data downloaded from the user’s network.