undefined

Authentication and Users

Every user has to authenticate with ConnectyCube before using any ConnectyCube functionality.

When someone connects with an application using ConnectyCube, the application will need to obtain a session token which provides temporary, secure access to ConnectyCube APIs.

A session token is an opaque string that identifies a user and an application.

Session token rights

There are different types of session tokens to support different use cases:

Session Token Type Description
Application session token This kind of access token is needed to read the app data. Has only READ access to resources
User session token The user token is the most commonly used type of token. This kind of access token is needed any time the app calls an API to read, modify or write a specific user's data on their behalf. Has READ/WRITE access to resources

Create session token

To create an application session use the following code:

// JS SDK v1
ConnectyCube.createSession((error, session) => {});

// JS SDK v2
ConnectyCube.createSession()
  .then((session) => {})
  .catch((error) => {});

To create a user session use the following code:

const userCredentials = { login: "cubeuser", password: "awesomepwd" };

// JS SDK v1
ConnectyCube.createSession(userCredentials, (error, session) => {});

// JS SDK v2
ConnectyCube.createSession(userCredentials)
  .then((session) => {})
  .catch((error) => {});

Upgrade session token (user login)

If you have an application session, you can upgrade it to a user session by calling login method:

const userCredentials = { login: "cubeuser", password: "awesomepwd" };
// const userCredentials = { email: 'cubeuser@gmail.com', password: 'awesomepwd' };
// const userCredentials = { provider: 'facebook', keys: {token: 'a876as7db...asg34dasd8wqe'} };

// JS SDK v1
ConnectyCube.login(userCredentials, (error, user) => {});

// JS SDK v2
ConnectyCube.login(userCredentials)
  .then((user) => {})
  .catch((error) => {});

Authentication via phone number

Sign In with phone number is supported with (Firebase integration).

You need to create Firebase project_id and obtain Firebase access_token after SMS code verification, then pass these parameters to login method:

const userCredentials = {
    "provider": "firebase_phone",
    "firebase_phone": {"project_id": "..." , "access_token": "..."}
};

// JS SDK v1
ConnectyCube.login(userCredentials, (error, user) => {});

// JS SDK v2
ConnectyCube.login(userCredentials)
  .then((user) => {})
  .catch((error) => {});

Important note: in order to login via phone number you need to create a session token first.

Authentication via external identity provider

Custom Identity Provider (CIdP) feature is necessary if you need to use an external database to authenticate ConnectyCube application users. It allows you to integrate your existing users base with ConnectyCube easily and works the same way as Facebook/Twitter SSO.

With Custom Identity Provider feature you can continue using your user database instead of storing/copying user data to ConnectyCube database.

More info available on a dedicated Custom Identity Provider guide page.

After the Custom Identity Provider configuration, you can use same ConnectyCube user login API to authenticate ConnectyCube users against an external identity provider base.

Create web session (mobile-to-web cross login with a QR code)

Create an empty web session and check it until it is upgraded by the mobile application side (iOS or Android, or JS mobile app).

To create the empty web session:

const params = {
  long: 1, // use `1` if you going to set session lifetime 30 days, or `0` to 2 hours
};

// JS SDK v1
ConnectyCube.createWebSession(params, (error, qrCodeSVG) => {
  // insert the QR code to your DOM:
  // document.getElementById('QR_code_container').innerHTML(qrCodeSVG)
});

// JS SDK v2
ConnectyCube.createWebSession(params)
  .then((qrCodeSVG) => {
    // insert the QR code to your DOM:
    // document.getElementById('QR_code_container').innerHTML(qrCodeSVG)
  })
  .catch((error) => {});

Start to check the session until it is updated after get QR code image from ConnectyCube.createWebSession(params, callback):

// JS SDK v1
const timer = ConnectyCube.checkWebSessionUntilUpgrade((error, session) => {
  // the upgraded session returns if success, or error if time is up.
});

// you can stop checking at any time
clearInterval(timer);

Scan the QR code image, get a web token and upgrade the web session:

// JS SDK v1
ConnectyCube.upgradeWebSession(webToken, (error) => {});

// JS SDK v2
ConnectyCube.upgradeWebSession(webToken).catch((error) => {});

There is some settings for check the web session in the ConnectyCube config:

const CONFIG = {
  webSession: {
    getSessionTimeInterval: 3, // a check web session interval in seconds
    getSessionTimeout: 120, // a check web session timeout in seconds
  },
};

ConnectyCube.init(CREDENTIALS, CONFIG);

Downgrade session token (user logout)

If you have a user session, you can downgrade it to an application session by calling logout method:

// JS SDK v1
ConnectyCube.logout((error) => {});

// JS SDK v2
ConnectyCube.logout().catch((error) => {});

Session expiration

Expiration time for session token is 2 hours after last request to API. If you perform query with expired token, you will receive the error Required session does not exist. In this case you need to recreate a session token.

There is a special callback function to handle this case:

const CONFIG = {
  on: {
    sessionExpired: (handleResponse, retry) => {
      // call handleResponse() if you do not want to process a session expiration,
      // so an error will be returned to origin request
      // handleResponse();

      // JS SDK v1
      ConnectyCube.createSession((error, session) => {
        retry(session);
      });

      // JS SDK v2
      ConnectyCube.createSession()
        .then(retry)
        .catch((error) => {});
    },
  },
};

ConnectyCube.init(CREDENTIALS, CONFIG);

Destroy session token

To destroy a session use the following code:

// JS SDK v1
ConnectyCube.destroySession((error) => {});

// JS SDK v2
ConnectyCube.destroySession().catch((error) => {});

User signup

const userProfile = {
  login: "marvin18",
  password: "supersecurepwd",
  email: "awesomeman@gmail.com",
  full_name: "Marvin Simon",
  phone: "47802323143",
  website: "https://dozensofdreams.com",
  tag_list: ["iphone", "apple"],
  custom_data: JSON.stringify({ middle_name: "Bartoleo" }),
};

// JS SDK v1
ConnectyCube.users.signup(userProfile, (error, user) => {});

// JS SDK v2
ConnectyCube.users
  .signup(userProfile)
  .then((user) => {})
  .catch((error) => {});

Only login (or email) + password are required.

User profile update

const updatedUserProfile = {
  login: "marvin18",
  full_name: "Marvin Simon",
};

// JS SDK v1
ConnectyCube.users.update(updatedUserProfile, (error, user) => {});

// JS SDK v2
ConnectyCube.users
  .update(updatedUserProfile)
  .then((user) => {})
  .catch((error) => {});

If you want to change your password, you need to provide 2 parameters: password and old_password. Updated user entity will be returned.

User avatar

You can set a user's avatar. You just need to upload it to the ConnectyCube cloud storage and then connect to user.

// for example, a file from HTML form input field
const inputFile = $("input[type=file]")[0].files[0];

const fileParams = {
  name: inputFile.name,
  file: inputFile,
  type: inputFile.type,
  size: inputFile.size,
  public: false,
};

const updateUser = (uploadedFile) => {
  const updatedUserProfile = { avatar: uploadedFile.uid };
  // JS SDK v1
  ConnectyCube.users.update(updatedUserProfile, (error, user) => {});
  // JS SDK v2
  ConnectyCube.users.update(updatedUserProfile);
};

// JS SDK v1
ConnectyCube.storage.createAndUpload(fileParams, (error, result) => {
  if (!error) {
    updateUser(result);
  }
});

// JS SDK v2
ConnectyCube.storage
  .createAndUpload(fileParams)
  .then(updateUser)
  .then((updatedUser) => {})
  .catch((error) => {});

Now, other users can get you avatar:

const avatarUID = updatedUser.avatar;
const avatarURL = ConnectyCube.storage.privateUrl(avatarUID);
const avatarHTML = "<img src='" + avatarURL + "' alt='photo'/>";

Password reset

It's possible to reset a password via email:

// JS SDK v1
ConnectyCube.users.resetPassword("awesomeman@gmail.com", (error) => {});

// JS SDK v2
ConnectyCube.users.resetPassword("awesomeman@gmail.com").catch((error) => {});

Retrieve users

Retrieve users by ID

const searchParams = { filter: { field: "id", param: "in", value: [22, 33] } };

// JS SDK v1
ConnectyCube.users.get(searchParams, (error, result) => {});

// JS SDK v2
ConnectyCube.users
  .get(searchParams)
  .then((result) => {})
  .catch((error) => {});

Retrieve user by login

const searchParams = { login: "marvin18" };

// JS SDK v1
ConnectyCube.users.get(searchParams, (error, result) => {});

// JS SDK v2
ConnectyCube.users
  .get(searchParams)
  .then((result) => {})
  .catch((error) => {});

Retrieve user by email

const searchParams = { email: "marvin18@example.com" };

// JS SDK v1
ConnectyCube.users.get(searchParams, (error, result) => {});

// JS SDK v2
ConnectyCube.users
  .get(searchParams)
  .then((result) => {})
  .catch((error) => {});

Retrieve users by full name

const searchParams = { full_name: "Marvin Samuel" };

// JS SDK v1
ConnectyCube.users.get(searchParams, (error, result) => {});

// JS SDK v2
ConnectyCube.users
  .get(searchParams)
  .then((result) => {})
  .catch((error) => {});

Retrieve user by phone number

const searchParams = { phone: "44678162873" };

// JS SDK v1
ConnectyCube.users.get(searchParams, (error, result) => {});

// JS SDK v2
ConnectyCube.users
  .get(searchParams)
  .then((result) => {})
  .catch((error) => {});

Retrieve user by external ID

const searchParams = { external_user_id: "675373912" };

ConnectyCube.users.get(searchParams, (error, user) => {});

Retrieve users by tags

const searchParams = { tags: ["apple"] };

// JS SDK v1
ConnectyCube.users.get(searchParams, (error, result) => {});

// JS SDK v2
ConnectyCube.users
  .get(searchParams)
  .then((result) => {})
  .catch((error) => {});

Delete user

A user can delete himself from the platform:

// JS SDK v1
ConnectyCube.users.delete((error) => {});

// JS SDK v2
ConnectyCube.users.delete().catch((error) => {});