undefined

Authentication and Authorization API

Overview

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. By default, session token is valid for 2 hours. Any API request prolongs the token validity for another 2 hours.

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

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

Session Token Type Description
App 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

Create a session means creation a token - a credential that can be used by an application to access an API. It informs the API that the bearer of the token has been authorized to access the API and perform specific actions specified by the scope that has been granted.

To get a token a request with the mandatory parameters should be sent on server.

Endpoint
POST https://api.connectycube.com/session
Parameters
Parameter Required Description
application_id Yes Identifier of the application created on server. Can be found in the admin panel
auth_key Yes Authentication key created and assigned for application automatically. Can be found in the application details in the admin panel
timestamp Yes Unix Timestamp. It shouldn't be differ from time provided by NTP more than 60 minutes. It is suggested that time on your devices is synchronised with NTP service
nonce Yes Unique Random number. Requests with the same timestamp and same value for nonce parameter can not be send twice
signature Yes Sequence of data that identifies request authenticity. Generated based on auth_secret

How to generate a 'signature' parameter?

The mandatory parameters required for creation a token should be written as a single line. Parameters shoud be written in the alphabetical order and append the ‘&’ character. Then, this sequense is passed to HMAC-SHA1 function and is signed with auth_secret (that is automatically created for application).

Session can be created for application only or with specifying user's details.

Request example
curl -X POST \
-H "Content-Type: application/json" \
-d '{"application_id": "1", "auth_key": "29WfrNWdvkhmX6V", "nonce": "4214611091", "timestamp": "1544010993",  "signature": "46fd163f78f52a0f8122d3758d6282923471d55f"}' \
https://api.connectycube.com/session
Response
{
  "session": {
    "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
  }
}

Create session with User authorization

To work with a user's details (add, update or delete), user's parameters should be specified in a request of session creation. At least the mandatory parameters should be specified in the request.

Endpoint
POST https://api.connectycube.com/session
Parameters
Parameter Required Description
user[login] Yes* User's login
user[email] Yes* User's email
user[password] Yes User's Password
provider Optional Possible values: facebook, twitter, firebase_phone, firebase_email
keys[token] Optional Social network provider's access token
keys[secret] Optional, for Twitter only Social network provider's access token secret
firebase_phone[project_id] Optional, for Firebase only Firebase project ID - the unique identifier for your Firebase project
firebase_phone[access_token] Optional, for Firebase only Firebase user's ID token
firebase_email[project_id] Optional, for Firebase only Firebase project ID - the unique identifier for your Firebase project
firebase_email[access_token] Optional, for Firebase only Firebase user's ID token

There are four available sets of data to specify when create a session with a user:

  • login and password
  • email and password
  • provider + keys[token] and keys[secret] - when sign up with Facebook or Twitter
  • provider + firebase_phone[project_id] and firebase_phone[access_token] - when sign up with a phone number
  • provider + firebase_email[project_id] and firebase_email[access_token] - when sign up with a email
Request example
curl -X POST \
-H "Content-Type: application/json" \
-d '{"application_id": "1", "auth_key": "29WfrNWdvkhmX6V", "nonce": "111", "timestamp": "1544010993",  "signature": "46fd163f78f52a0f8122d3758d6282923471d55f", "user":{"login": "john", "password": "11111111"}}' \
https://api.connectycube.com/session
Response
{
    "session": {
        "id": 111,
        "user_id": 111,
        "application_id": 1,
        "nonce": 111,
        "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 session with Guest User

Session can be created with temporary guest user, user will be automatically created, session with guest user valid for 1 day after user will be automatically deleted.
NOTE: Guest user can't be authorized by login/email password

Parameters
Parameter Required Description
user[guest] No Define creating session with temporary guest user
user[full_name] No Set guest user full_name
Request example
curl -X POST \
-H "Content-Type: application/json" \
-d '{"application_id": "1", "auth_key": "29WfrNWdvkhmX6V", "nonce": "1647", "timestamp": "1678966390",  "signature": "71fd163f78f52a0fc132d3758d6282923471d3df", "user":{"guest": "1", "full_name": "Olof Shodger"}}' \
https://api.connectycube.com/session
Response
{
    "session": {
        "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": 900265,
        "id": 900265,
        "user": {
            "_id": "6412fe76d6600d1d3d67877d",
            "id": 900265,
            "created_at": "2023-03-16T11:33:10Z",
            "updated_at": "2023-03-16T11:33:10Z",
            "login": "guest_login_328A465366359BDDB984904D49EAD187B524",
            "full_name": "Olof Shodger",
            "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
        }
    }
}

User Sign In

To have an ability to sign in with a User, this User should be previously registered. This can be done with 'User sign up' request.

Endpoint
POST https://api.connectycube.com/login
Parameters
Parameter Required Description
login Yes* User login
email Yes* User email
password Yes User password
provider Optional Login with external systems like facebook, twitter or firebase_phone, firebase_email.
keys[token] Optional Access token provided by the external system the User is going to login with
keys[secret] Optional, for Twitter only Social network provider's access token secret.
firebase_phone[project_id] Optional Firebase project ID - the unique identifier for your Firebase project.
firebase_phone[access_token] Optional Firebase user's ID token
firebase_email[project_id] Optional Firebase project ID - the unique identifier for your Firebase project.
firebase_email[access_token] Optional Firebase user's ID token

There are four available sets of data to specify when authenticate a user:

  • login and password
  • email and password
  • provider + keys[token] and keys[secret] - when sign up with Facebook or Twitter
  • provider + firebase_phone[project_id] and firebase_phone[access_token] - when sign up with a phone number
  • provider + firebase_email[project_id] and firebase_email[access_token] - when sign up with a email
Request example
curl -X POST \
-H "Content-Type: application/json" \
-H "CB-Token:  <TOKEN>" \
-d '{"login": "johnsmith", "password": "7665727zxc"}' \
https://api.connectycube.com/login
Response
{
  "user": {
    "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
  }
}

User Sign Out

User's sign out request downgrades user's session to application session. The further work with a User isn't allowed.

Endpoint
DELETE https://api.connectycube.com/login
Request example
curl -X DELETE \
-H "CB-Token:  <TOKEN>" \
https://api.connectycube.com/login
Response
Status: 200

Get information about session

Retriving information about the current (active) session from token specified as a header.

Endpoint
GET https://api.connectycube.com/session
Request example
curl -X GET \
-H "CB-Token:  <TOKEN> "\
https://api.connectycube.com/session
Response
{
  "session": {
    "id": 219606,
    "user_id": 47592,
    "application_id": 212,
    "nonce": 1422,
    "token": "66e8aef2757404f3c7c2488f17ebdd8b8a0000d4",
    "ts": 1544083714,
    "created_at": "2018-12-06T08:08:35Z",
    "updated_at": "2018-12-06T08:08:35Z",
    "user": {
      "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-06T08:08:35Z",
      "last_request_at": "2018-12-06T08:08:35Z",
      "external_user_id": null,
      "facebook_id": null,
      "twitter_id": null,
      "blob_id": null,
      "custom_data": null,
      "avatar": null,
      "user_tags": null
    }
  }
}

Destroy session

The request destroys all of the data associated with the current session.

Endpoint
DELETE https://api.connectycube.com/session
Request example
curl -X DELETE \
-H "CB-Token:  <TOKEN> "\
https://api.connectycube.com/session
Response
Status: 200