recognize-sdk

Recognize Node Wrapper

Recognize is a simple and secure user authentication as a service. Essentially, it's a login system.

• Easy to use dashboard & API
• Extremely secure
• Completely free for now!

We're continuously working on new features for Recognize. We'll only introduce a paid plan once we've created a lot of cool stuff. Even after that, we'll always have a generous free plan.

Getting Started

It's super easy to get started with Recognize.

There are two main things: users and logins. You create a user whenever someone signs up, users then create logins.

Creating a user (Sign ups)

var recognize = require("recognize-sdk")("key_sec_demo_key")
 
recognize.users.create({
  email: "[e-mail]",
  password: "does whatever a spider can"
})
.then(function(user) {
  console.log(user)
})

Logging in

var recognize = require("recognize-sdk")("key_sec_demo_key")
 
recognize.logins.create({
  email: "[e-mail]",
  password: "does whatever a spider can"
})
.then(function(login) {
  //You should save login.id to a cookie, it is used to verify the login on next load.
  console.log(login)
})

A more secure & complete integration is provided by Recognize.js's popup() in the browser. You might prefer using it.

Verifying a login

Once a user has logged in, they probably will make more requests, like logging in at yourApp.com/login and then accessing their dashboard at yourApp.com/dashboard.

Just save the login.id you received when you created the login (by using cookies, for example) and verify it for new requests.

var recognize = require("recognize-sdk")("key_sec_demo_key")
 
recognize.logins.verify("LOGIN ID")
.then(function(verified) {
  console.log(verified) //verified.login & verified.user
})

All Functions

Users

Create a user

recognize.users.create(details)

details should at least include:

• email - The email address of the user.
• password - The password they'd like to login with.

It may optionally include:

• name - The user's name.
• phone - The user's phone number.
• profile_picture - The user's profile picture URL.
• metadata - A key/value object which has any other data you'd like to store (Like a user's birthday).
• two_factor_auth_enabled - Boolean, whether 2FA should be enabled. If true, an additional object, two_factor_auth with the keys secret, recovery_codes and qr_uri, is also returned.
• password_reset_required - Boolean. If true, will force the user to reset their password on login.
• disabled - Boolean. If true, the user won't be able to login.

---

Retrieve a user

recognize.users.get(userID)

---

Update a user

recognize.users.update(userID, update)

update can include any key/value described for recognize.users.create()

---

Delete a user

recognize.users.delete(userID)

---

List all users

recognize.users.list(options)

options can be used for pagination & searching users:

• limit - The number of users to return, between 1 and 100.

• starting_after - The last user you received's ID, will return the users after this one.

• email - Searches users with this email address.

• disabled - Boolean, searches disabled or enabled users.

• two_factor_auth_enabled - Boolean, searches users who have disabled or enabled two factor authentication.

• created_after - Searches users created after this time (in epoch seconds).

• created_before - Searches users created before this time (in epoch seconds).

• password_last_updated_after - Searches users who last updated their password after this time (in epoch seconds).

• password_last_updated_before - Searches users who last updated their password before this time (in epoch seconds).

So, to find first 50 users created since yesterday who haven't enabled two factor authentication, we can do:

recognize.users.list({limit: 50, created_after: time() - (60 * 60 * 24), two_factor_auth_enabled: false})
 
function time() { return Math.floor(new Date() / 1000) }

---

Logins

Create a login

recognize.logins.create(details)

details should at least include:

• email - The email address of the user.
• password - The user's password.

It may optionally include:

• user_agent - The user agent of the device creating this login (Used for verification).
• ip - The IP address of the device creating this login (Used for verification).
• metadata - A key/value object which has any other data you'd like to store.

When you create a login, you may need to update it before it's active.

login.status can be active, failed, logged_out, pending_password_reset, pending_login_verification or pending_two_factor_auth.

If the status starts with pending_, you'll have to update it with a new_password for pending_password_reset, or a verification_code for pending_two_factor_auth & pending_login_verification.

If you use Recognize.js's popup() in the browser, it'll automatically handle these statuses.

---

Verify a login

recognize.logins.verify(loginID, options)

options may include:

• user_agent - The user agent of current device (Used for verification).
• ip - The IP address of current device (Used for verification).

---

Retrieve a login

recognize.logins.get(loginID)

---

Update a login

recognize.logins.update(loginID, update)

update may include:

• status - Currently you can only set this to logged_out, this will only work if this login is active.
• verification_code - The two factor authentication code or emailed login verification code or recovery code. You can only set this when the status is pending_two_factor_auth or pending_login_verification.
• new_password - The new password for this user. You can only set this when the status is pending_password_reset.
• metadata - A key/value object which has any other data you'd like to store.

---

List all logins

recognize.logins.list(options)

options can be used for pagination & searching logins:

• limit - The number of logins to return, between 1 and 100.

• starting_after - The last login you received's ID, will return the logins after this one.

• user - Searches logins of this user (ID).

• status - Searches logins with this status. Value can be active, failed, logged_out, pending_password_reset, pending_login_verification or pending_two_factor_auth.

• ip - Searches logins created by this IP address.

• created_after - Searches logins created after this time (in epoch seconds).

• created_before - Searches logins created before this time (in epoch seconds).

So, to find first 50 logins of the user usr_test which are active:

recognize.logins.list({limit: 50, user: "usr_test", status: "active"})
 

---

Recognize.js

It's sometimes better to use Recognize.js directly in the browser. It's more secure and integrates more easily.

<script src="https://js.getrecognize.com/v1"></script>
 
<script>
var recognize = Recognize("key_pub_demo_key")
//recognize.logins.create, recognize.logins.update and recognize.users.create still available.
 
//Popup automatically handles everything.
var popup = recognize.popup()
 
popup.on("login", function(login) {
  console.log(login)
})
 
popup.show()
</script>