Introduction
cURL Node

API Reference

Recognize is a simple and secure authentication as a service.
You can use Recognize to manage your users and their logins.

Recognize API is RESTful and uses standard HTTP features. It responds using JSON.
We support CORS (But please ensure that any client side code only uses your public API key).
Want to create a user? Just POST to /users.

The example requests will work as is. Though you should replace the demo key with your own API key.
Get your API key here.

SDKs

You can use a pre-built SDK to quickly integrate Recognize into your code.

We currently have official SDKs for browsers and NodeJS.


The Node SDK functions return Promises.

Base URL

https://api.getrecognize.com/v1

Authentication

Authentication makes sure only you can manage your users.
We use HTTP Basic authentication. We also support Bearer auth.

Simply provide your secret API key as the username or password for Basic authentication, or as the token for Bearer authentication.
Simply provide your your secret API key while initializing the SDK:
var recognize = require("recognize-sdk")("YOUR API KEY HERE")


API keys are really powerful. Please always keep them safe. Never share them.
You should use your public API key for browser side requests. They can only create users and logins.

Example

curl https://api.getrecognize.com/v1/users \
-u YOUR_API_KEY_HERE:
var recognize = require("recognize-sdk")("YOUR API KEY")

Errors

Recognize uses HTTP status codes to indicate the success or failure of a request.
2xx status codes mean the request was successful and 4xx or 5xx status codes mean there was an error.
Additionally, in the response success will be false and an error object will be included.

Error Object

message
A text message that describes this error. You can show this directly to the user if error.type is login_error or user_error,
code
The HTTP status code.
type
The type of error. Values are described in the Error Types table.
param Optional
The parameter that's causing this error.

Status Codes

200
The request was successful.
400
An invalid parameter was provided.
401
No valid API key provided.
402
The parameters were valid but this request failed (Example: When we automatically logout a suspicious login).
404
No such resource exists.
429
Rate limited. You're making too many requests.
500
Something went wrong with Recognize.

Example Error Response

{
  "success": false,
  "error": {
    "message": "A user with this email already exists.",
    "code": 400,
    "type": "user_error",
    "param": "email"
  }
}

Error Types

authentication_error
No valid API key was provided.
invalid_request_error
You provided an invalid parameter to the API.
login_error
An error related with logging in a user.
user_error
An error related with updating or creating a user (Email address already taken).
api_error
An error occured with Recognize API (These are rare).
rate_limit_error
You're making too many requests to the API. Slow them down.

Versioning

When we make radical changes, we release them in new, dated versions of the API.
You can view API versions and changes here.

By default, requests will use the latest API version unless a specific version is specified.
To set a specific API version, specify the version using the Recognize-Version header.
To set a specific API version, specify the version when initializing the SDK:
var recognize = require("recognize-sdk")("YOUR API KEY", {version: "API VERSION"})

Example

curl https://api.getrecognize.com/v1/users \
  -u YOUR_API_KEY_HERE: \
  -h "Recognize-Version: API_VERSION"
var Recognize = require("recognize-sdk"),
  recognize = Recognize("KEY", {version: "API VERSION"})

Users

User objects represent the customers or users of your company.
You can create, retrieve, update, list, or delete users.

Create a user

Arguments

email Required
The email address of this user. No two users can have the same email address.
password Required
The login password for this user.
name Optional
This user's name.
phone Optional
This user's phone number.
profile_picture Optional
A URL for this user's profile picture.
two_factor_auth_enabled Optional
Boolean. If true, the result will also have a two_factor_auth object with secret, qr_uri and recovery_codes keys, use them to help setup 2FA for the user as they'll have to authenticate all logins.
password_reset_required Optional
Boolean. If true, the user will be required to reset their password on login.
disabled Optional
Boolean. If true, the user will not be able to login.
metadata Optional
Object. You can store any other data you may have in this object.
POST
/users

Example Request

curl https://api.getrecognize.com/v1/users \
  -u key_sec_demo_key: \
  -d email="[email protected]" \
  -d password="does whatever a spider can"
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.users.create({
  email: "[email protected]",
  password: "does whatever a spider can"
}).then(function(user) {
  //Do something.
})

Example Response

{
  "success": true,
  "id": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
  "object": "user",
  "name": null,
  "profile_picture": null,
  "email": "[email protected]",
  "phone": null,
  "two_factor_auth_enabled": false,
  "password_reset_required": false,
  "password_last_updated": 1539428053,
  "disabled": false,
  "metadata": {},
  "created": 1539428053,
  "url": "/v1/users/usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3"
}

Retrieve a user

Retrieve the details of an existing user, you'll only need the user ID.
GET
/users/id

Example Request

curl https://api.getrecognize.com/v1/users/usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3 \
  -u key_sec_demo_key:
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.users.get("usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3")
.then(function(user) {
  //Do something.
})

Example Response

{
  "success": true,
  "id": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
  "object": "user",
  "name": null,
  "profile_picture": null,
  "email": "[email protected]",
  "phone": null,
  "two_factor_auth_enabled": false,
  "password_reset_required": false,
  "password_last_updated": 1539428053,
  "disabled": false,
  "metadata": {},
  "created": 1539428053,
  "url": "/v1/users/usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3"
}

Update a user

You can update the following data of any user, you'll need the user ID.

Arguments

email
The email address of this user. No two users can have the same email address.
password
The login password for this user.
name
This user's name.
phone
This user's phone number.
profile_picture
A URL for this user's profile picture.
two_factor_auth_enabled
Boolean. If true, the result will also have a two_factor_auth object with secret, qr_uri and recovery_codes keys, use them to help setup 2FA for the user as they'll have to authenticate all logins.
password_reset_required
Boolean. If true, the user will be required to reset their password on login.
disabled
Boolean. If true, the user will not be able to login.
metadata
Object. You can store any other data you may have in this object.
POST
/users/id

Example Request

curl https://api.getrecognize.com/v1/users/usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3 \
  -u key_sec_demo_key: \
  -d name="Peter"
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.users.update("usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3", {
  name: "Peter"
}).then(function(user) {
  //Do something.
})

Example Response

{
  "success": true,
  "id": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
  "object": "user",
  "name": "Peter",
  "profile_picture": null,
  "email": "[email protected]",
  "phone": null,
  "two_factor_auth_enabled": false,
  "password_reset_required": false,
  "password_last_updated": 1539428053,
  "disabled": false,
  "metadata": {},
  "created": 1539428053,
  "url": "/v1/users/usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3"
}

Delete a user

Once you delete a user, their email address can be used to create another account.
If you don't want this, just disable the user rather than deleting them.
DELETE
/users/id

Example Request

curl https://api.getrecognize.com/v1/users/usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3 \
  -u key_sec_demo_key: \
  -X DELETE
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.users.delete("usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3")
.then(function(deleted) {
  //Do something.
})

Example Response

{
  "success": true,
  "id": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
  "object": "user",
  "deleted": true
}

List all users

By default, we'll return the 10 latest users.
To paginate, you should use the limit and starting_after arguments.
You can also search users by using the arguments.

Arguments

limit Optional, default is 10
The number of users to return, between 1 and 100.
starting_after Optional
The ID of the last user you handled, returns the users after this one.
email Optional
Returns users with this email address.
disabled Optional
Returns either disabled or enabled users, depending on this boolean.
two_factor_auth_enabled Optional
Returns either users without 2FA or with 2FA, depending on this boolean.
created_after Optional
Returns users created after this unix epoch timestamp.
created_before Optional
Returns users created before this unix epoch timestamp.
password_last_updated_after Optional
Returns users who updated their password after this unix epoch timestamp.
password_last_updated_before Optional
Returns users who updated their password before this unix epoch timestamp.
GET
/users

Example Request

curl https://api.getrecognize.com/v1/users \
  -u key_sec_demo_key:
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.users.list()
.then(function(users) {
  //Do something.
})

Example Response

{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
      "object": "user",
      "name": "Peter",
      "profile_picture": null,
      "email": "[email protected]",
      "phone": null,
      "two_factor_auth_enabled": false,
      "password_reset_required": false,
      "password_last_updated": 1539428053,
      "disabled": false,
      "metadata": {},
      "created": 1539428053,
      "url": "/v1/users/usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3"
    }
  ],
  "has_more": false,
  "url": "/v1/users"
}

Logins

Logins are created by users to log them into your application.
You can create, verify, update, retrieve, update, or list logins.

Create a login

This is equivalent to logging in.
You should save the login.id in a cookie so that you can verify this login later.

It's easier to just use Recognize.js's Popup() in the browser, it automatically handles logins and signups for you.


Note: If login.status isn't active, you'll have to update the login with a verification_code if the status is pending_two_factor_auth or pending_login_verification, or with a new_password for the user if the status is pending_password_reset.

Arguments

email Required
The email address of this user.
password Required
The password of this user.
user_agent Optional
The browser user agent, used while verifying a login.
ip Optional
The device's IP address, used while verifying a login.
metadata Optional
Object. You can store any other data you may have in this object.
POST
/logins

Example Request

curl https://api.getrecognize.com/v1/logins \
  -u key_sec_demo_key: \
  -d email="[email protected]" \
  -d password="does whatever a spider can"
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.logins.create({
  email: "[email protected]",
  password: "does whatever a spider can"
}).then(function(login) {
  //Do something.
})

Example Response

{
  "success": true,
  "id": "lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846",
  "object": "login",
  "status": "active",
  "method": "password",
  "user": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
  "device": {
    "user_agent": "RecognizeNode/1.0.5",
    "ip": "52.34.31.193",
    "country": "US"
  },
  "metadata": {},
  "created": 1540061597,
  "url": "/v1/logins/lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846"
}

Verify a login

You should verify a login whenever a request to a user page is made.

Note: Verifying a login on every request will make a huge performance hit once you've scaled, it's better to cache already verified logins.

Arguments

user_agent Optional
Current browser's user agent, used for verification.
ip Optional
Curent device's IP address, used for verification.
GET
/verify/loginID

Example Request

curl https://api.getrecognize.com/v1/verify/lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846 \
  -u key_sec_demo_key:
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.logins.verify("lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846")
.then(function(verified) {
  //Do something.
})

Example Response

{
  "success": true,
  "login": {
    "id": "lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846",
    "object": "login",
    "status": "active",
    "method": "password",
    "user": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
    "device": {
      "user_agent": "RecognizeNode/1.0.5",
      "ip": "52.34.31.193",
      "country": "US"
    },
    "metadata": {},
    "created": 1540061597,
    "url": "/v1/logins/lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846"
  },
  "user": {
    "id": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
    "object": "user",
    "name": "Peter",
    "profile_picture": null,
    "email": "[email protected]",
    "phone": null,
    "two_factor_auth_enabled": false,
    "password_reset_required": false,
    "password_last_updated": 1539428053,
    "disabled": false,
    "metadata": {},
    "created": 1539428053,
    "url": "/v1/users/usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3"
  }
}

Update a login

You can update a login with any of the arguments below:

Arguments

status
The status of this login. Currently, this can only be set to logged_out, and only if the current status is active.
verification_code
If the status is pending_login_verification, this should be the emailed verification code. If the status is pending_two_factor_auth, this should be the 2FA code or a recovery code.
new_password
The new password for this user, this can only be set if the current status is pending_password_reset.
metadata
Object. You can store any other data you may have in this object.
POST
/logins/id

Example Request

curl https://api.getrecognize.com/v1/logins \
  -u key_sec_demo_key: \
  -d email="[email protected]" \
  -d password="does whatever a spider can"
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.logins.create({
  email: "[email protected]",
  password: "does whatever a spider can"
}).then(function(login) {
  //Do something.
})

Example Response

{
  "success": true,
  "id": "lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846",
  "object": "login",
  "status": "active",
  "method": "password",
  "user": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
  "device": {
    "user_agent": "RecognizeNode/1.0.5",
    "ip": "52.34.31.193",
    "country": "US"
  },
  "metadata": {},
  "created": 1540061597,
  "url": "/v1/logins/lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846"
}

Forgot password

Forgot password is a special method of logging in.

The login starts off with the status pending_login_verification. Once you enter the code we emailed the user, the login status will move to pending_password_reset. Finally, once you enter the new password, the login should become active.

Arguments

status
The status of this login. Currently, this can only be set to logged_out, and only if the current status is active.
verification_code
If the status is pending_login_verification, this should be the emailed verification code. If the status is pending_two_factor_auth, this should be the 2FA code or a recovery code.
new_password
The new password for this user, this can only be set if the current status is pending_password_reset.
metadata
Object. You can store any other data you may have in this object.
POST
/forgot_password

Example Request

curl https://api.getrecognize.com/v1/forgot_password \
  -u key_sec_demo_key: \
  -d email="[email protected]"
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.logins.forgot_password({
  email: "[email protected]"
}).then(function(login) {
  //Do something.
})

Example Response

{
  "success": true,
  "id": "lgn_jnhwg1990001di4n1zs9p5effnC59zRCm020928dc7e73547d29aacac0567dc9e34",
  "object": "login",
  "status": "pending_login_verification",
  "method": "forgot_password",
  "user": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
  "device": {
    "user_agent": "RecognizeNode/1.0.5",
    "ip": "54.213.253.5",
    "country": "US"
  },
  "metadata": {},
  "created": 1540067532,
  "url": "/v1/logins/lgn_jnhwg1990001di4n1zs9p5effnC59zRCm020928dc7e73547d29aacac0567dc9e34"
}

Retrieve a login

Retrieve the details of an existing login, you'll only need the login ID.
GET
/logins/id

Example Request

curl https://api.getrecognize.com/v1/logins/lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846 \
  -u key_sec_demo_key:
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.logins.get("lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846")
.then(function(login) {
  //Do something.
})

Example Response

{
  "success": true,
  "id": "lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846",
  "object": "login",
  "status": "active",
  "method": "password",
  "user": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
  "device": {
    "user_agent": "RecognizeNode/1.0.5",
    "ip": "52.34.31.193",
    "country": "US"
  },
  "metadata": {},
  "created": 1540061597,
  "url": "/v1/logins/lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846"
}

List all logins

By default, we'll return the 10 latest logins.
To paginate, you should use the limit and starting_after arguments.
You can also search logins by using the arguments.

Arguments

limit Optional, default is 10
The number of logins to return, between 1 and 100.
starting_after Optional
The ID of the last login you handled, returns the logins after this one.
user Optional
The ID of an user. When set, only logins of this user will be returned.
status Optional
Returns logins currently in this status. Values can be active, logged_out, failed, pending_two_factor_auth, pending_login_verification, or pending_password_reset.
ip Optional
Returns logins created by this IP address.
created_after Optional
Returns logins created after this unix epoch timestamp.
created_before Optional
Returns logins created before this unix epoch timestamp.
GET
/logins

Example Request

curl https://api.getrecognize.com/v1/logins?limit=1 \
  -u key_sec_demo_key:
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.logins.list({limit: 1})
.then(function(logins) {
  //Do something.
})

Example Response

{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "lgn_jnhwg1990001di4n1zs9p5effnC59zRCm020928dc7e73547d29aacac0567dc9e34",
      "object": "login",
      "status": "pending_login_verification",
      "method": "forgot_password",
      "user": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
      "device": {
        "user_agent": "RecognizeNode/1.0.5",
        "ip": "54.213.253.5",
        "country": "US"
      },
      "metadata": {},
      "created": 1540067532,
      "url": "/v1/logins/lgn_jnhwg1990001di4n1zs9p5effnC59zRCm020928dc7e73547d29aacac0567dc9e34"
    }
  ],
  "has_more": true,
  "url": "/v1/logins"
}

Events

Whenever something notable happens, an event is generated.
Like when a user signs up, or a login is updated to logged out.

Events can also be sent to your server using webhooks.
You can set up a webhook here.

Retrieve an event

You can retrieve an event by its ID.

Event Types

user.created
A user was created.
user.updated
A user was updated.
user.deleted
A user was deleted.
login.created
A login was created.
login.updated
A login was updated.
GET
/events/id

Example Request

curl https://api.getrecognize.com/v1/events/evt_jnhswuc40004cw9zav901knwaQOpEpNABO \
  -u key_sec_demo_key:
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.events.get("evt_jnhswuc40004cw9zav901knwaQOpEpNABO")
.then(function(event) {
  //Do something.
})

Example Response

{
  "success": true,
  "id": "evt_jnhswuc40004cw9zav901knwaQOpEpNABO",
  "object": "event",
  "type": "login.created",
  "data": {
    "object": {
      "id": "lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846",
      "object": "login",
      "status": "active",
      "method": "password",
      "user": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
      "device": {
        "user_agent": "RecognizeNode/1.0.5",
        "ip": "52.34.31.193",
        "country": "US"
      },
      "created": 1540061597,
      "url": "/v1/logins/lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846"
    }
  },
  "request": "req_jnhswrc60002cw9zc5o8igot",
  "api_version": "2018-08-26",
  "created": 1540061598,
  "url": "/v1/events/evt_jnhswuc40004cw9zav901knwaQOpEpNABO"
}

List all events

By default, we'll return the 10 latest events.
To paginate, you should use the limit and starting_after arguments.
You can also search events by using the arguments.

Arguments

limit Optional, default is 10
The number of events to return, between 1 and 100.
starting_after Optional
The ID of the last event you handled, returns the events after this one.
type Optional
Returns a specific type of events. Valid values are listed in the Event Types table above.
created_after Optional
Returns events created after this unix epoch timestamp.
created_before Optional
Returns events created before this unix epoch timestamp.
GET
/events

Example Request

curl https://api.getrecognize.com/v1/events?limit=1 \
  -u key_sec_demo_key:
var recognize = require("recognize-sdk")("key_sec_demo_key")

recognize.events.list({limit: 1})
.then(function(events) {
  //Do something.
})

Example Response

{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "evt_jnhswuc40004cw9zav901knwaQOpEpNABO",
      "object": "event",
      "type": "login.created",
      "data": {
        "object": {
          "id": "lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846",
          "object": "login",
          "status": "active",
          "method": "password",
          "user": "usr_jn7bpsbc0032ob9zi1csq1h0hnlm401Ad3",
          "device": {
            "user_agent": "RecognizeNode/1.0.5",
            "ip": "52.34.31.193",
            "country": "US"
          },
          "created": 1540061597,
          "url": "/v1/logins/lgn_jnhswtqb0003cw9zywx8r7vzPyyAXIAJXT4546062ef8cd4a0db09f8bafaa916846"
        }
      },
      "request": "req_jnhswrc60002cw9zc5o8igot",
      "api_version": "2018-08-26",
      "created": 1540061598,
      "url": "/v1/events/evt_jnhswuc40004cw9zav901knwaQOpEpNABO"
    }
  ],
  "has_more": true,
  "url": "/v1/events"
}