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 Value. 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" \
-H "CB-Token: <TOKEN>" \
-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
keys[token] Optional Social network provider's access token
keys[secret] Optional, for Twitter only Social network provider's access token secret
firebase[project_id] Optional, for Firebase only Firebase project ID - the unique identifier for your Firebase project
firebase[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[project_id] and firebase[access_token] - when sign up with a phone number
Request example
curl -X POST \
-H "Content-Type: application/json" \
-H "CB-Token: <TOKEN>" \
-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": 32534,
        "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
        }
    }
}

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.
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

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[project_id] and firebase[access_token] - when sign up with a phone number
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

Create Web session

ConnectyCube API allows users to be logged in on the Web application by scanning the login code with app on your phone. Keep in mind that you cannot use your app's QR code scanner to scan QR codes outside of the ones used to log into your Web app, though you can always use your smartphone to scan other QR codes. Web client makes a request to server to create an empty long session with a QR code.

Endpoint
POST https://api.connectycube.com/session/web
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 Value. 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
long No Optional Integer Parameter that allows to create session that will expire in a month after being created. If not specifed session is valid for 2 hours
Request example
curl -X POST \
-H "Content-Type: application/json" \
-H "CB-Token:  <TOKEN>" \
-d '{"application_id":"1","auth_key": "29WfrNWdvkhmX6V","nonce": "222","timestamp": "1541604768","signature":"d9dcac6e294dc5403ec6f80603fda92107277a9b","long":1}' \
https://api.connectycube.com/session/web
Response
{
    "session": {
        "application_id": 1,
        "created_at": "2018-11-07T15:33:30Z",
        "id": 25072,
        "nonce": 222,
        "token": "4763f1603593759654d96e50b563f8244d000001",
        "ts": 1541604768,
        "updated_at": "2018-11-07T15:33:30Z",
        "user_id": 0,
        "_id": "25072"
    },
    "qr_code": "<?xml version=\"1.0\" standalone=\"yes\"?>\n<svg version=\"1.1\" xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" xmlns:ev=\"http://www.w3.org/2001/xml-events\" width=\"407\" height=\"407\" shape-rendering=\"crispEdges\">\n<rect width=\"11\" height=\"11\" x=\"0\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"11\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"22\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"33\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"44\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"55\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"66\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"110\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"121\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"132\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"154\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"165\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"198\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\" x=\"231\" y=\"0\" style=\"fill:#000\"/><rect width=\"11\" height=\"11\"
}

Patch Web session

After web session is been created a mobile client sends a request to server to patch this session with own user id.

Endpoint
PATCH https://api.connectycube.com/session/web
Parameters
Parameter Required Description
web_token Yes Web token that was created in a 'Create Web session' request
Request example
curl -X PATCH \
-H "Content-Type: application/json" \
-H "CB-Token:  <TOKEN>" \
-d '{"web_token":"4763f1603593759654d96e50b563f8244d000001"}' \
https://api.connectycube.com/session/web
Response
Status: 200

Get session list

Retriving information about all active sessions.

Endpoint
GET https://api.connectycube.com/session/list
Request example
curl -X GET \
-H "CB-Token: <TOKEN>" \
https://api.connectycube.com/session/list
Response
[
    {
        "session_id": 24829,
        "ip": "197.12.22.27",
        "last_activity": "2018-11-07T13:49:16Z",
        "user_agent": "http://url.com",
        "location": null
    },
    {
        "session_id": 27161,
        "ip": "76.22.214.71",
        "last_activity": "2018-11-16T09:36:52Z",
        "user_agent": "PostmanRuntime/7.4.0",
        "location": null
    },
    {
        "session_id": 32491,
        "ip": "37.12.34.11",
        "last_activity": "2018-12-05T09:51:46Z",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
        "location": ""
    }
]

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 all sessions except the current one

In case when users want to make log out from other sessions (devices), they are able to make a request to destroy all sessions except the current one.

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

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