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:
ConnectyCube.createSession()
.then((session) => {})
.catch((error) => {});
Response example from ConnectyCube.createSession()
:
{
"application_id": 1,
"created_at": "2018-10-01T10:47:01Z",
"device_id": null,
"id": 151,
"nonce": 4214611091,
"token": "5a7bc95d85c0eb2bf052be3d29d3df523081e80y",
"ts": 1542560252,
"updated_at": "2018-10-01T10:47:01Z",
"user_id": null
}
To create a user session use the following code:
const userCredentials = { login: "cubeuser", password: "awesomepwd" };
ConnectyCube.createSession(userCredentials)
.then((session) => {})
.catch((error) => {});
Response example from ConnectyCube.createSession(userCredentials)
:
{
"id": 152,
"user_id": 81,
"application_id": 1,
"nonce": 4214611091,
"token": "83153a14fb2df777c2f866178902a4bb15000001",
"ts": 1544010993,
"created_at": "2018-12-05T11:58:02Z",
"updated_at": "2018-12-05T11:58:02Z",
"user": {
"id": 81,
"full_name": "John Smith",
"email": "johnsmith@domain.com",
"login": "john",
"phone": "380665787842",
"website": null,
"created_at": "2018-06-15T14:20:54Z",
"updated_at": "2018-12-05T11:58:02Z",
"last_request_at": "2018-12-05T11:58:02Z",
"external_user_id": null,
"facebook_id": null,
"twitter_id": null,
"custom_data": "",
"blob_id": null,
"avatar": "",
"user_tags": null
}
}
Create guest session
To create a session with guest user use the following code:
const guestUserCredentials = { guest: '1', full_name: 'Awesome Smith' };
ConnectyCube.createSession(guestUserCredentials)
.then((session) => {})
.catch((error) => {});
Response example from ConnectyCube.createSession(guestUserCredentials)
:
{
"application_id": 1,
"token": "3E5CDBE3743E33DC820E012BF81BCD77ABFF",
"created_at": "2023-03-16T11:33:10Z",
"updated_at": "2023-03-16T11:33:10Z",
"nonce": 1647,
"ts": 1678966390,
"user_id": 900266,
"id": 900266,
"user": {
"_id": "6412fe76d6600d1d3d67877c",
"id": 900266,
"created_at": "2023-03-16T11:33:10Z",
"updated_at": "2023-03-16T11:33:10Z",
"login": "guest_login_728A465366369BDDB984904D49EAC187B578",
"full_name": "Awesome Smith",
"is_guest": true,
"last_request_at": null,
"timezone": null,
"email": null,
"phone": "",
"website": null,
"twitter_id": null,
"external_user_id": null,
"facebook_id": null,
"custom_data": null,
"user_tags": null,
"avatar": null,
"external_id": null
}
}
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'} };
ConnectyCube.login(userCredentials)
.then((user) => {})
.catch((error) => {});
Response example from ConnectyCube.login(userCredentials)
:
{
"id": 47592,
"full_name": "John Smith",
"email": "johnsmith@gmail.com",
"login": "johnsmith",
"phone": null,
"website": null,
"created_at": "2018-11-23T09:42:36Z",
"updated_at": "2018-12-06T07:56:26Z",
"last_request_at": "2018-12-06T07:59:22Z",
"external_user_id": null,
"facebook_id": null,
"twitter_id": null,
"blob_id": null,
"custom_data": null,
"avatar": null,
"user_tags": null
}
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]": "...",
"firebase_phone[access_token]": "...",
};
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 Firebase email
Sign In with email is supported with (Firebase integration).
You need to create Firebase project_id
and obtain Firebase access_token
after email/password verification, then pass these parameters to login
method:
const userCredentials = {
provider: 'firebase_email',
firebase_email: {
project_id: 'XXXXXXXXXXX',
access_token: 'XXXXXXXXXXXYYYYYY'
}
};
ConnectyCube.login(userCredentials)
.then((user) => {})
.catch((error) => {});
Important note: in order to login via email 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.
Downgrade session token (user logout)
If you have a user session, you can downgrade it to an application session by calling logout
method:
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();
ConnectyCube.createSession()
.then(retry)
.catch((error) => {});
},
},
};
ConnectyCube.init(CREDENTIALS, CONFIG);
Destroy session token
To destroy a session use the following code:
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" }),
};
ConnectyCube.users
.signup(userProfile)
.then((user) => {})
.catch((error) => {});
Response example from ConnectyCube.users.signup(userProfile)
:
{
"id": 81,
"full_name": "Marvin Simon",
"email": "awesomeman@gmail.com",
"login": "marvin18",
"phone": "47802323143",
"website": "https://dozensofdreams.com",
"created_at": "2018-06-15T14:20:54Z",
"updated_at": "2018-12-05T11:58:02Z",
"last_request_at": "2018-12-05T11:58:02Z",
"external_user_id": null,
"facebook_id": null,
"twitter_id": null,
"custom_data": "{\"middle_name\":\"Bartoleo\"}",
"blob_id": null,
"avatar": "",
"user_tags": "iphone,apple"
}
Only login (or email) + password are required.
User profile update
const updatedUserProfile = {
login: "marvin18sim",
full_name: "Mar Sim",
};
ConnectyCube.users
.update(updatedUserProfile)
.then((user) => {})
.catch((error) => {});
Response example from ConnectyCube.users.update(updatedUserProfile)
:
{
"id": 81,
"full_name": "Mar Sim",
"email": "awesomeman@gmail.com",
"login": "marv18sim",
"phone": "47802323143",
"website": "https://dozensofdreams.com",
"created_at": "2018-06-15T14:20:54Z",
"updated_at": "2018-12-05T11:58:02Z",
"last_request_at": "2018-12-05T11:58:02Z",
"external_user_id": null,
"facebook_id": null,
"twitter_id": null,
"custom_data": "{\"middle_name\": \"Bartoleo\"}",
"blob_id": null,
"avatar": "",
"user_tags": "iphone,apple"
}
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 };
return ConnectyCube.users.update(updatedUserProfile);
};
ConnectyCube.storage
.createAndUpload(fileParams)
.then(updateUser)
.then((updatedUser) => {})
.catch((error) => {});
Response example from ConnectyCube.storage.createAndUpload(fileParams)
:
{
"account_id": 7,
"app_id": 12,
"blob_object_access": {
"blob_id": 421517,
"expires": "2020-10-06T15:51:38Z",
"id": 421517,
"object_access_type": "Write",
"params": "https://s3.amazonaws.com/cb-shared-s3?Content-Type=text%2Fplain..."
},
"blob_status": null,
"content_type": "text/plain",
"created_at": "2020-10-06T14:51:38Z",
"id": 421517,
"name": "awesome.txt",
"public": false,
"set_completed_at": null,
"size": 11,
"uid": "7cafb6030d3e4348ba49cab24c0cf10800",
"updated_at": "2020-10-06T14:51:38Z"
}
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:
ConnectyCube.users
.resetPassword("awesomeman@gmail.com")
.then((result) => {})
.catch((error) => {});
If provided email is valid - an email with password reset instruction will be sent to it.
Retrieve users V2
Examples
Retrieve users by ID
const searchParams = {
limit: 10,
offset: 50,
id: { in: [51941, 51946] }
}
ConnectyCube.users.getV2(searchParams)
.then((result) => {})
.catch((error) => {});
Retrieve users by login
const searchParams = { login: 'adminFirstUser' }
ConnectyCube.users.getV2(searchParams)
.then((result) => {})
.catch((error) => {});
Retrieve users by last_request_at
const date = new Date(2017, 10, 10)
const searchParams = { last_request_at: { gt: date } }
ConnectyCube.users.getV2(searchParams)
.then((result) => {})
.catch((error) => {});
More information (fields, operators, request rules) available here
Retrieve users V1 (Deprecated)
Retrieve users by ID (Deprecated)
const params = {
page: 1,
per_page: 5,
filter: {
field: "id",
param: "in",
value: [51941, 51946],
},
};
ConnectyCube.users
.get(params)
.then((result) => {})
.catch((error) => {});
Response example from ConnectyCube.users.get(params)
- see
Retrieve user by login (Deprecated)
const searchParams = { login: "marvin18" };
ConnectyCube.users
.get(searchParams)
.then((result) => {})
.catch((error) => {});
Retrieve user by email (Deprecated)
const searchParams = { email: "marvin18@example.com" };
ConnectyCube.users
.get(searchParams)
.then((result) => {})
.catch((error) => {});
Retrieve users by full name (Deprecated)
const searchParams = { full_name: "Marvin Samuel" };
ConnectyCube.users
.get(searchParams)
.then((result) => {})
.catch((error) => {});
Retrieve user by phone number (Deprecated)
const searchParams = { phone: "44678162873" };
ConnectyCube.users
.get(searchParams)
.then((result) => {})
.catch((error) => {});
Retrieve user by external ID (Deprecated)
const searchParams = { external_user_id: "675373912" };
ConnectyCube.users
.get(searchParams)
.then((result) => {})
.catch((error) => {});
Retrieve users by tags (Deprecated)
const searchParams = { tags: ["apple"] };
ConnectyCube.users
.get(searchParams)
.then((result) => {})
.catch((error) => {});
Delete user
A user can delete himself from the platform:
ConnectyCube.users
.delete()
.then((result) => {})
.catch((error) => {});