Authentication and Authorization API
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
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
Response
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
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
andpassword
email
andpassword
provider
+keys[token]
andkeys[secret]
- when sign up with Facebook or Twitterprovider
+firebase_phone[project_id]
andfirebase_phone[access_token]
- when sign up with a phone numberprovider
+firebase_email[project_id]
andfirebase_email[access_token]
- when sign up with a email
Request example
Response
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
Response
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
Parameters
Parameter | Required | Description |
---|---|---|
login | Yes* | User login |
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
andpassword
email
andpassword
provider
+keys[token]
andkeys[secret]
- when sign up with Facebook or Twitterprovider
+firebase_phone[project_id]
andfirebase_phone[access_token]
- when sign up with a phone numberprovider
+firebase_email[project_id]
andfirebase_email[access_token]
- when sign up with a email
Request example
Response
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
Request example
Response
Get information about session
Retriving information about the current (active) session from token specified as a header.
Endpoint
Request example
Response
Destroy session
The request destroys all of the data associated with the current session.