Authentication and Authorization

Ask tech team
From QuickBlox Developers (API docs, code samples, SDK)
Jump to: navigation, search

Contents

Authenticating requests

When someone connects with an app using QuickBlox, the app will be able to obtain an access token which provides temporary, secure access to QuickBlox APIs.

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

Session tokens are obtained via Create Session request.

Then, because of privacy checks, all REST API requests must be authenticated with a token - the QB-Token header of each request to REST API must contain valid session token.

Expiration time for session token is 2 hours after last request to REST API. Be aware about it. If you will perform query with expired token - you will receive error Required session does not exist. In this case you have to recreate a session token.

Each REST API response contains header QB-Token-ExpirationDate which contains session token expiration date.

Access Tokens rights

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 QuickBlox data on their behalf.
Has READ/WRITE access to resources

Signature generation

HMAC-SHA function of the body of the request, with a key auth_secret. Request body is formed as the sorted (sorting alphabetically, as symbols, not as bytes) by increase the string array 'parameter=value', separated with the symbol "&". For the parameters passed as a user[login]=amigo30 is used just such a line of user[login]=amigo30

Example of body:
application_id=22&auth_key=wJHd4cQSxpQGWx5&nonce=33432&timestamp=1326966962

Example of body with user:
application_id=22&auth_key=wJHd4cQSxpQGWx5&nonce=33432&timestamp=1326966962&user[login]=amigo30&user[password]=amigo30pass

Example of body with social token(Facebook):
application_id=22&auth_key=wJHd4cQSxpQGWx5&keys[token]=AM46dxjhisdffgry26282352fdusdfusdfgsdf&nonce=33432&provider=facebook&timestamp=1326966962


Authentication and Authorization API

Requests and Responses

URL HTTP Verb Action Description Success HTTP Status Code
/session.json POST API Session Creation Or API User Sing In 201
/login.json POST API User Sign In 202
/login.json DELETE API User Sign Out 200
/session.json DELETE API Session Destroy 200
/session.json GET API Session Info 200


API Session Creation

To receive the session token you have to authenticate your application by requesting url with obligatory parameters.

Usually there are 6 sets of parameters you can pass:

  • minimal set of parameters (to create App session token)
  • minimal set of parameters plus user[login]/user[email] and user[password] (to create User session token)
  • minimal set of parameters plus provider=facebook, keys[token] (to create User session token based on Facebook user)
  • minimal set of parameters plus provider=twitter, keys[token] and keys[secret] (to create User session token based on Twitter user)
  • minimal set of parameters plus provider=twitter_digits, twitter_digits[X-Auth-Service-Provider] and twitter_digits [X-Verify-Credentials-Authorization] (to create User session token based on Twitter Digits user (SMS))
  • minimal set of parameters plus provider=firebase_phone, firebase_phone[project_id] and firebase_phone[access_token] (to create User session token based on Firebase phone user (SMS))

Parameters

Minimal Set Of Request Parameters
Param Required Type Value Example Description
application_id Yes Integer 1 API Application Identifier
auth_key Yes String ypqdqEx7sOeWEQr Authentication Key
timestamp Yes Integer 1325162213 Unix Timestamp It shouldn't be differ from time provided by NTP more than 60 minutes. We suggest you synchronize time on your devices with NTP service.
nonce Yes Integer 3234 Unique Random Value. Requests with the same timestamp and same value for nonce parameter can not be send twice.
signature Yes String a0b03a2bfe32117aa 805ee36d6e87f970097e341

Follow Signature generation guide

You also could authorize user with the same request, just specify user login (or email) and password or pass social credentials.

Extended Set Of Request Parameters
Param Required Type Value Example Description
user[login] Optional* String bukster API User login
user[email] Optional* String mymail@quickblox.com API User email
user[password] Optional String bad-as-passwd API User password
provider Optional String facebook Possible values: facebook, twitter, twitter_digits, firebase_phone
keys[token] Optional String AM46dxjhisdffgry26282352fdusdfusdfgsdf Social network provider's access token
keys[secret] Optional, only for Twitter String t35400dfzxcxvsdfn76gancHDHoad7a7fs Social network provider's access token secret
twitter_digits[X-Auth-Service-Provider] Optional, only for Twitter Digits String https://api.digits.com/1.1/sdk/account.json Twitter Digits auth header
twitter_digits[X-Verify-Credentials-Authorization] Optional, only for Twitter Digits String OAuth oauth_signature=\"VPAnnk%2BX5gl9%2FWfImtlX%2F7a1erk%3D\", oauth_nonce=\"BAAA38FB-6DC2-42F7-94F9-762775E318FC\", oauth_timestamp=\"1455617205\", oauth_consumer_key=\"yvr9bDxidLTaydLo7JZRtGIAp\", oauth_token=\"3533173695-3FS9DzsV0L16kA63lOC7c7MCMw7m2xVGWfbs8pK\", oauth_version=\"1.0\", oauth_signature_method=\"HMAC-SHA1\" Twitter Digits auth header
firebase[project_id] Optional, only for Firebase String my_app_project_id Firebase project ID - the unique identifier for your Firebase project.
firebase[access_token] Optional, only for Firebase String t35400d....fzxcxvsdfn Firebase user's ID token.

* Only email(if user has it) or login required

Request

curl -X POST \
-H "QuickBlox-REST-API-Version: 0.1.0" \
-d "application_id=140&auth_key=7quWEh-k6TqghXe&timestamp=1326964049&nonce=414546828&signature=e6e603c251a569e70a2f27a8c71b5017e81e05d5" \
https://api.quickblox.com/session.json

Response

{
  "session": {
    "application_id": 2,
    "created_at": "2012-04-03T07:34:48Z",
    "device_id": null,
    "id": 743,
    "nonce": 1308205278,
    "token": "0e7bc95d85c0eb2bf052be3d29d3df523081e87f",
    "ts": 1333438438,
    "updated_at": "2012-04-03T07:34:48Z",
    "user_id": null
  }
}


With User authorization

Request

curl -X POST \
-H "Content-Type: application/json" \
-H "QuickBlox-REST-API-Version: 0.1.0" \
-d '{"application_id": "2", "auth_key": "DtF9cZPqTF8Wy9Q", "timestamp": "1333630580", "nonce": "1340569516", "signature": "13293a5bd2026b957ebbb36c89d9649aae9e5503", "user": {"login": "injoit", "password": "injoit"}}' \
https://api.quickblox.com/session.json

Response

{
  "session": {
    "application_id": 2,
    "created_at": "2012-04-03T07:41:12Z",
    "device_id": null,
    "id": 744,
    "nonce": 289239351,
    "token": "25b29b8c8d6f2d3afbf1d437cc611b23741fc7ee",
    "ts": 1333438822,
    "updated_at": "2012-04-03T07:41:13Z",
    "user_id": 3
  }
}


API User Sign In

After you allow users to sign up, you need to let them log in to their account with a login/email and password in the future. You must provide the user's login or email address along with a password when authenticating users that are registered in QuickBlox. The following login options are possible:

  • Login with login/email and password
  • Login via Facebook by providing provider=facebook and keys[token] parameters.
  • Login via Twitter by providing provider=twitter, keys[token] and keys[secret] parameters.
  • Login via Twitter Digits (SMS) by providing provider=twitter_digits, twitter_digits[X-Auth-Service-* Provider] and twitter_digits[X-Verify-Credentials-Authorization] parameters.
  • Login via Firebase phone number (SMS) by providing provider=firebase_phone, firebase_phone[project_id] and firebase_phone[access_token] parameters.

Parameters

Param Required Type Value Example Description
login Optional* String mylogin API User login
email Optional* String mymail@quickblox.com API User email
password Optional String mypassword API User password
provider Optional String facebook Possible providers: facebook, twitter, twitter_digits, firebase_phone.
keys[token] Optional String AM46dxjhisdffgry26282352fdusdfusdfgsdf Social network provider's access token
keys[secret] Optional, only for Twitter String t35400dfzxcxvsdfn76gancHDHoad7a7fs Social network provider's access token secret.
twitter_digits[X-Auth-Service-Provider] Optional, only for Twitter Digits String https://api.digits.com/1.1/sdk/account.json Twitter Digits auth header
twitter_digits[X-Verify-Credentials-Authorization] Optional, only for Twitter Digits String OAuth oauth_signature=\"VPAnnk%2BX5gl9%2FWfImtlX%2F7a1erk%3D\", oauth_nonce=\"BAAA38FB-6DC2-42F7-94F9-762775E318FC\", oauth_timestamp=\"1455617205\", oauth_consumer_key=\"yvr9bDxidLTaydLo7JZRtGIAp\", oauth_token=\"3533173695-3FS9DzsV0L16kA63lOC7c7MCMw7m2xVGWfbs8pK\", oauth_version=\"1.0\", oauth_signature_method=\"HMAC-SHA1\" Twitter Digits auth header
firebase_phone[project_id] Optional String my_app_project_id Firebase project ID - the unique identifier for your Firebase project.
firebase_phone[access_token] Optional String t35400d....fzxcxvsdfn Firebase user's ID token.

* Only email(if user has it) OR login required

Request

curl -X POST \
-H "Content-Type: application/json"\
-H "QuickBlox-REST-API-Version: 0.1.0" \
-H "QB-Token: cf5709d6013fdb7a6787fbeb8340afed8aec4c69" \
-d '{"login": "injoit", "password": "injoit"}' \
https://api.quickblox.com/login.json

Response

{
  "blob_id": null,
  "created_at": "2012-01-16T08:13:38Z",
  "custom_parameters": null,
  "email": null,
  "external_user_id": 111,
  "facebook_id": null,
  "full_name": null,
  "id": 3,
  "last_request_at": "2012-04-04T10:27:40Z",
  "login": "injoit",
  "phone": null,
  "twitter_id": null,
  "twitter_digits_id": null,
  "updated_at": "2012-04-04T10:27:40Z",
  "website": null,
  "user_tags":"superman"
}


API Session Destroy

Destroy session

Parameters

Param Required Type Value Example Description
token Yes String 422ce2791d7070b88a82f415b3693c81612e3423 Session's token

Request

curl -X DELETE \
-H "QuickBlox-REST-API-Version: 0.1.0" \
-H "QB-Token: 8b75a6c7191285499d890a81df4ee7fe49bc732a" \
https://api.quickblox.com/session.json

Response

Status: 200, null


API User Sign Out

Destroy user session (Session token will be decreased to the token of the application)

Parameters

Param Required Type Value Example Description
token Yes String 422ce2791d7070b88a82f415b3693c81612e3423 Session's token

Request

curl -X DELETE \
-H "QuickBlox-REST-API-Version: 0.1.0" \
-H "QB-Token: 8b75a6c7191285499d890a81df4ee7fe49bc732a" \
https://api.quickblox.com/login.json

Response

Status: 200, null


API Session Info

Get info about current session

Request

curl -X GET \
-H "QuickBlox-REST-API-Version: 0.1.0" \
-H "QB-Token: 8b75a6c7191285499d890a81df4ee7fe49bc732a" \
https://api.quickblox.com/session.json

Response

{"session": {
  "_id":"541ae9sda5c12e21e000316",
  "application_id":123,
  "created_at":"2014-09 18T14:15:41Z",
  "device_id":0,
  "nonce":1331361499,
  "token":"8b75a6c7191285499d890a81df4ee7fe49bc732a",
  "ts":1411049740,
  "updated_at":"2014-09-18T14:42:03Z",
  "user_id":0,
  "id":64340
 }
}


Examples

PHP

PHP session creation example

Python

Python session creation example

Pascal

Pascal session creation discussion