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) {
}
});