undefined

Authentication and Users

Every user needs 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

Session token management

Android SDK supports automatic session management, so you do not need to create a session token on Android manually:

  • on your 1st request to API the session token will be created automatically
  • when the session expires, any further API request will renew it.

You can track session states using ConnectyCubeSessionManager class and SessionListener listener:

SDK v2 kotlin

//for now can be checked
ConnectycubeSessionManager.isActiveSessionValid()

SDK v1 kotlin

ConnectycubeSessionManager.getInstance().addListener(
    object : ConnectycubeSessionManager.SessionListener {
        override fun onSessionCreated(session: ConnectycubeSession) {

        }

        override fun onSessionUpdated(sessionParameters: ConnectycubeSessionParameters) {

        }

        override fun onSessionDeleted() {

        }

        override fun onSessionRestored(session: ConnectycubeSession) {

        }

        override fun onSessionExpired() {

        }

        override fun onProviderSessionExpired(provider: String) {

        }
    }
)

SDK v1 java

ConnectycubeSessionManager.getInstance().addListener(new ConnectycubeSessionManager.SessionListener() {
   @Override
   public void onSessionCreated(ConnectycubeSession session) {

   }

   @Override
   public void onSessionUpdated(ConnectycubeSessionParameters sessionParameters) {

   }

   @Override
   public void onSessionDeleted() {

   }

   @Override
   public void onSessionRestored(ConnectycubeSession session) {

   }

   @Override
   public void onSessionExpired() {

   }

   @Override
   public void onProviderSessionExpired(String provider) {

   }
});

Session token details

At any time you can get details about your current session token:

SDK v2 kotlin

ConnectycubeSessionManager.activeSession.user

SDK v1 kotlin

val sessionParameters = ConnectycubeSessionManager.getInstance().sessionParameters
sessionParameters.userId
sessionParameters.userLogin
sessionParameters.userEmail
sessionParameters.socialProvider
sessionParameters.accessToken

SDK v1 java

ConnectycubeSessionParameters sessionParameters = ConnectycubeSessionManager.getInstance().getSessionParameters();
sessionParameters.getUserId();
sessionParameters.getUserLogin();
sessionParameters.getUserEmail();
sessionParameters.getSocialProvider();
sessionParameters.getAccessToken();

Also you can check whether you are logged in or not:

SDK v2 kotlin

val isSignedIn = ConnectycubeSessionManager.activeSession.user != null

SDK v1 kotlin

val isSignedIn = ConnectycubeSessionManager.getInstance().sessionParameters != null

SDK v1 java

boolean isSignedIn = ConnectycubeSessionManager.getInstance().getSessionParameters() != null;

Upgrade session token (user login)

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

SDK v2 kotlin

val userToLogin = ConnectycubeUser(login = "marvin18", password = "supersecurepwd")
ConnectyCube.signIn(userToLogin, { user -> }, { error -> })

SDK v1 kotlin

val user = ConnectycubeUser().apply {
    login = "marvin18"
    password = "supersecurepwd"
}

ConnectycubeUsers.signIn(user).performAsync(object : EntityCallback<ConnectycubeUser> {
    override fun onSuccess(user: ConnectycubeUser, args: Bundle) {

    }

    override fun onError(error: ResponseException) {

    }
})

SDK v1 java

final ConnectycubeUser user = new ConnectycubeUser();
user.setLogin("marvin18");
user.setPassword("supersecurepwd");

ConnectycubeUsers.signIn(user).performAsync(new EntityCallback<ConnectycubeUser>() {
    @Override
    public void onSuccess(ConnectycubeUser user, Bundle args) {

    }

    @Override
    public void onError(ResponseException error) {

    }
});

Authentication via phone number

Sign In with phone number is supported with Firebase integration.

The whole guide on how to create Firebase project, connect Firebase SDK and implement authentication via phone number is available at our Firebase Setup Guide. Please follow it.

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.

Downgrade session token (user logout)

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

SDK v2 kotlin

ConnectyCube.signOut({ }, { error -> })

SDK v1 kotlin

ConnectycubeUsers.signOut().performAsync(object : EntityCallback<Void?> {
    override fun onSuccess(result: Void?, params: Bundle) {

    }

    override fun onError(responseException: ResponseException) {

    }
})

SDK v1 java

ConnectycubeUsers.signOut().performAsync(new EntityCallback<Void>() {
    @Override
    public void onSuccess(Void result, Bundle params) {

    }

    @Override
    public void onError(ResponseException responseException) {

    }
});

Session expiration

Expiration time for session token is 2 hours after the last request to API is made. But you do not need to worry about it - with the automatic session token management it will be renewed automatically with next request to API.

Destroy session token

To destroy a session use the following code:

SDK v2 kotlin

ConnectyCube.destroySession({ }, { error -> })

SDK v1 kotlin

ConnectycubeAuth.deleteSession().performAsync(object : EntityCallback<Void?> {
    override fun onSuccess(result: Void?, params: Bundle) {

    }

    override fun onError(responseException: ResponseException) {

    }
})

SDK v1 java

ConnectycubeAuth.deleteSession().performAsync(new EntityCallback<Void>() {
    @Override
    public void onSuccess(Void result, Bundle params) {

    }

    @Override
    public void onError(ResponseException responseException) {

    }
});

User signup

SDK v2 kotlin

val userTags = listOf("iphone", "apple")

val userToSignUp = ConnectycubeUser(login = "marvin18", password = "supersecurepwd").apply {
    email = "awesomeman@gmail.com"
    fullName = "Marvin Simon"
    phone = "47802323143"
    website = "https://dozensofdreams.com"
    tags = userTags.joinToString(",")
}

ConnectyCube.signUp(userToSignUp, { user -> }, { error -> })

SDK v1 kotlin

val userTags = StringifyArrayList<String>().apply {
    add("iphone")
    add("apple")
}

val user = ConnectycubeUser("marvin18", "supersecurepwd").apply {  
    login = "marvin18"
    password = "supersecurepwd"
    email = "awesomeman@gmail.com"
    fullName = "Marvin Simon"
    phone = "47802323143"
    website = "https://dozensofdreams.com"
    tags = userTags
}

ConnectycubeUsers.signUp(user).performAsync(object : EntityCallback<ConnectycubeUser> {
    override fun onSuccess(user: ConnectycubeUser, args: Bundle) {

    }

    override fun onError(error: ResponseException) {

    }
})

SDK v1 java

final ConnectycubeUser user = new ConnectycubeUser("marvin18", "supersecurepwd");
user.setLogin("marvin18");
user.setPassword("supersecurepwd");
user.setEmail("awesomeman@gmail.com");
user.setFullName("Marvin Simon");
user.setPhone("47802323143");
user.setWebsite("https://dozensofdreams.com");
StringifyArrayList<String> tags = new StringifyArrayList<String>();
tags.add("iphone");
tags.add("apple");
user.setTags(tags);

ConnectycubeUsers.signUp(user).performAsync(new EntityCallback<ConnectycubeUser>() {
    @Override
    public void onSuccess(ConnectycubeUser user, Bundle args) {

    }

    @Override
    public void onError(ResponseException error) {

    }
});

Only login (or email) + password are required. Other fields are optional.

User profile update

SDK v2 kotlin

val userToUpdate = ConnectycubeUser(login = "marvin18", password = "supersecurepwd")
ConnectyCube.updateUser(userToUpdate, { user -> }, { error -> })

SDK v1 kotlin

val user = ConnectycubeUser().apply {
    login = "marvin18"
    fullName = "Marvin Simon"
}

ConnectycubeUsers.updateUser(user).performAsync(object : EntityCallback<ConnectycubeUser> {
    override fun onSuccess(user: ConnectycubeUser, args: Bundle) {

    }

    override fun onError(error: ResponseException) {

    }
})

SDK v1 java

ConnectycubeUser user = new ConnectycubeUser();
user.setLogin("marvin18");
user.setFullName("Marvin Simon");

ConnectycubeUsers.updateUser(user).performAsync(new EntityCallback<ConnectycubeUser>() {
    @Override
    public void onSuccess(ConnectycubeUser user, Bundle args) {

    }

    @Override
    public void onError(ResponseException error) {

    }
});

If you want to change your password, you need to provide 2 parameters: password and oldPassword. An 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.

SDK v2 kotlin

val imageFile: File = ...
ConnectyCube.uploadFile(imageFile.path, successCallback = { cubeFile ->
    val jo = JsonObject()
    jo.add("avatar_uid", JsonPrimitive(cubeFile.uid))
    user.customData = jo.toString()

    ConnectyCube.updateUser(user, { user -> }, { error -> })
}, errorCallback = { ex ->  })

SDK v1 kotlin

val imageFile: File = ...
ConnectycubeStorage.uploadFileTask(imageFile, false, null).performAsync(object: EntityCallback<ConnectycubeFile> {
    override fun  onSuccess(connectycubeFile: ConnectycubeFile, params: Bundle) {
        val jo = JsonObject()
        jo.add("avatar_uid", JsonPrimitive(connectycubeFile.uid))
        user.customData = jo.toString()

        ConnectycubeUsers.updateUser(user).performAsync(...)
    }

    override fun onError(responseException: ResponseException) {

    }
})

SDK v1 java

File imageFile = ...
ConnectycubeStorage.uploadFileTask(imageFile, false, null).performAsync(new EntityCallback<ConnectycubeFile>() {
    @Override
    public void onSuccess(ConnectycubeFile connectycubeFile, Bundle params) {
        JsonObject jo = new JsonObject();
        jo.add("avatar_uid", new JsonPrimitive(connectycubeFile.getUid()));
        user.setCustomData(jo.toString());

        ConnectycubeUsers.updateUser(user).performAsync(...);
    }

    @Override
    public void onError(ResponseException responseException) {

    }
});

Now, other users can get you avatar:

SDK v2 kotlin

val obj = JsonParser().parse(user.customData).asJsonObject
val fileUID = obj.getAsJsonPrimitive("avatar_uid").asString
val avatarUrl = getPrivateUrlForUID(fileUID)

SDK v1 kotlin

val obj = JsonParser().parse(user.customData).asJsonObject
val fileUID = obj.getAsJsonPrimitive("avatar_uid").asString
val avatarUrl = ConnectycubeFile.getPrivateUrlForUID(fileUID)

SDK v1 java

JsonObject obj = new JsonParser().parse(user.getCustomData()).getAsJsonObject();
String fileUID = obj.getAsJsonPrimitive("avatar_uid").getAsString();
String avatarUrl = ConnectycubeFile.getPrivateUrlForUID(fileUID);

Password reset

It's possible to reset a password via email:

SDK v2 kotlin

ConnectyCube.resetPassword("awesomeman@gmail.com", {}, { error -> })

SDK v1 kotlin

ConnectycubeUsers.resetPassword("awesomeman@gmail.com").performAsync(object : EntityCallback<Void?> {
    override fun onSuccess(result: Void?, params: Bundle) {

    }

    override fun onError(responseException: ResponseException) {

    }
})

SDK v1 java

ConnectycubeUsers.resetPassword("awesomeman@gmail.com").performAsync(new EntityCallback<Void>() {
    @Override
    public void onSuccess(Void result, Bundle params) {

    }

    @Override
    public void onError(ResponseException responseException) {

    }
});

If provided email is valid - an email with password reset instruction will be sent to it.

Retrieve users

Retrieve users by ID

SDK v2 kotlin

val usersIds = setOf(22, 23)
ConnectyCube.getUsersByIds(usersIds, {usersResult -> }, { error -> })

SDK v1 kotlin

val pagedRequestBuilder = PagedRequestBuilder().apply {
    page = 1
    perPage = 50
}

val usersIds: MutableList<Int> = ArrayList<Int>().apply {
    add(22)
    add(23)
}

val params = Bundle()

ConnectycubeUsers.getUsersByIDs(usersIds, pagedRequestBuilder, params).performAsync(object : EntityCallback<ArrayList<ConnectycubeUser>> {
    override fun onSuccess(users: ArrayList<ConnectycubeUser>, args: Bundle) {

    }

    override fun onError(error: ResponseException) {

    }
})

SDK v1 java

PagedRequestBuilder pagedRequestBuilder = new PagedRequestBuilder();
pagedRequestBuilder.setPage(1);
pagedRequestBuilder.setPerPage(50);

List<Integer> usersIds = new ArrayList<>();
usersIds.add(22);
usersIds.add(23);

Bundle params = new Bundle();

ConnectycubeUsers.getUsersByIDs(usersIds, pagedRequestBuilder, params).performAsync(new EntityCallback<ArrayList<ConnectycubeUser>>() {
    @Override
    public void onSuccess(ArrayList<ConnectycubeUser> users, Bundle args) {

    }

    @Override
    public void onError(ResponseException error) {

    }
});

Retrieve user by login

SDK v2 kotlin

ConnectyCube.getUserByLogin("amigo", {user -> }, { error -> })

SDK v1 kotlin

ConnectycubeUsers.getUserByLogin("amigo").performAsync(object : EntityCallback<ConnectycubeUser> {
    override fun onSuccess(user: ConnectycubeUser, args: Bundle) {

    }

    override fun onError(error: ResponseException) {

    }
})

SDK v1 java

ConnectycubeUsers.getUserByLogin("amigo").performAsync(new EntityCallback<ConnectycubeUser>() {
    @Override
    public void onSuccess(ConnectycubeUser user, Bundle args) {

    }

    @Override
    public void onError(ResponseException error) {

    }
});

Retrieve user by email

SDK v2 kotlin

ConnectyCube.getUserByEmail("amigo@gmail.com", {user -> }, { error -> })

SDK v1 kotlin

ConnectycubeUsers.getUserByEmail("amigo@gmail.com").performAsync(object : EntityCallback<ConnectycubeUser> {
    override fun onSuccess(user: ConnectycubeUser, args: Bundle) {

    }

    override fun onError(error: ResponseException) {

    }
})

SDK v1 java

ConnectycubeUsers.getUserByEmail("amigo@gmail.com").performAsync(new EntityCallback<ConnectycubeUser>() {
    @Override
    public void onSuccess(ConnectycubeUser user, Bundle args) {

    }

    @Override
    public void onError(ResponseException error) {

    }
});

Retrieve users by full name

SDK v2 kotlin

ConnectyCube.getUsersByFullName("Marvin Samuel", {usersResult -> }, { error -> })

SDK v1 kotlin

val pagedRequestBuilder = PagedRequestBuilder().apply {
    page = 1
    perPage = 50
}

val params = Bundle()

ConnectycubeUsers.getUsersByFullName("Marvin Samuel", pagedRequestBuilder, params)
    .performAsync(object : EntityCallback<ArrayList<ConnectycubeUser>> {
        override fun onSuccess(users: ArrayList<ConnectycubeUser>, args: Bundle) {

        }

        override fun onError(error: ResponseException) {

        }
    })

SDK v1 java

PagedRequestBuilder pagedRequestBuilder = new PagedRequestBuilder();
pagedRequestBuilder.setPage(1);
pagedRequestBuilder.setPerPage(50);

Bundle params = new Bundle();

ConnectycubeUsers.getUsersByFullName("Marvin Samuel", pagedRequestBuilder, params).performAsync(new EntityCallback<ArrayList<ConnectycubeUser>>() {
    @Override
    public void onSuccess(ArrayList<ConnectycubeUser> users, Bundle args) {

    }

    @Override
    public void onError(ResponseException error) {

    }
});

Retrieve user by phone number

SDK v2 kotlin

ConnectyCube.getUserByPhoneNumber("+4427123314", {user -> }, { error -> })

SDK v1 kotlin

val pagedRequestBuilder = PagedRequestBuilder().apply {
    page = 1
    perPage = 50
}

val usersPhones: ArrayList<String> = ArrayList<String>().apply {
    add("+4427123314")
}

val params = Bundle()

ConnectycubeUsers.getUsersByPhoneNumbers(usersPhones, pagedRequestBuilder, params)
    .performAsync(object : EntityCallback<ArrayList<ConnectycubeUser>> {
        override fun onSuccess(users: ArrayList<ConnectycubeUser>, args: Bundle) {

        }

        override fun onError(error: ResponseException) {

        }
    })

SDK v1 java

PagedRequestBuilder pagedRequestBuilder = new PagedRequestBuilder();
pagedRequestBuilder.setPage(1);
pagedRequestBuilder.setPerPage(50);

Bundle params = new Bundle();

ArrayList<String> usersPhones = new ArrayList<>();
usersPhones.add("+4427123314");

ConnectycubeUsers.getUsersByPhoneNumbers(usersPhones, pagedRequestBuilder, params).performAsync(new EntityCallback<ArrayList<ConnectycubeUser>>() {
    @Override
    public void onSuccess(ArrayList<ConnectycubeUser> users, Bundle args) {

    }

    @Override
    public void onError(ResponseException error) {

    }
});

Retrieve user by external ID

SDK v1 kotlin

ConnectycubeUsers.getUserByExternalId("3789").performAsync(object : EntityCallback<ConnectycubeUser> {
    override fun onSuccess(users: ConnectycubeUser, args: Bundle) {

    }

    override fun onError(error: ResponseException) {

    }
})

SDK v1 java

ConnectycubeUsers.getUserByExternalId("3789").performAsync(new EntityCallback<ConnectycubeUser>() {
    @Override
    public void onSuccess(ConnectycubeUser users, Bundle args) {

    }

    @Override
    public void onError(ResponseException error) {

    }
});

Retrieve users by tags

SDK v2 kotlin

val userTags = setOf("iphone")
ConnectyCube.getUsersByTags(userTags, {usersResult -> }, { error -> })

SDK v1 kotlin

val pagedRequestBuilder = PagedRequestBuilder().apply {
    page = 1
    perPage = 50
}

val userTags: ArrayList<String> = ArrayList<String>().apply {
    add("iphone")
}

val params = Bundle()

ConnectycubeUsers.getUsersByTags(userTags, pagedRequestBuilder, params)
    .performAsync(object : EntityCallback<ArrayList<ConnectycubeUser>> {
        override fun onSuccess(users: ArrayList<ConnectycubeUser>, args: Bundle) {

        }

        override fun onError(error: ResponseException) {

        }
    })

SDK v1 java

PagedRequestBuilder pagedRequestBuilder = new PagedRequestBuilder();
pagedRequestBuilder.setPage(1);
pagedRequestBuilder.setPerPage(50);

ArrayList<String> userTags = new ArrayList<>();
userTags.add("iphone");

Bundle params = new Bundle();

ConnectycubeUsers.getUsersByTags(userTags, pagedRequestBuilder, params).performAsync(new EntityCallback<ArrayList<ConnectycubeUser>>() {
    @Override
    public void onSuccess(ArrayList<ConnectycubeUser> users, Bundle args) {

    }

    @Override
    public void onError(ResponseException error) {

    }
});

Delete user

A user can delete himself from the platform:

SDK v2 kotlin

ConnectyCube.deleteUser({}, { error -> })

SDK v1 kotlin

ConnectycubeUsers.deleteUser().performAsync(object : EntityCallback<Void?> {
    override fun onSuccess(result: Void?, params: Bundle) {

    }

    override fun onError(responseException: ResponseException) {

    }
})

SDK v1 java

ConnectycubeUsers.deleteUser().performAsync(new EntityCallback<Void>() {
    @Override
    public void onSuccess(Void result, Bundle params) {

    }

    @Override
    public void onError(ResponseException responseException) {

    }
});