Authentication and Authorization

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

Contents

Summary

To send requests and receive responses from QuickBlox your Application must be authenticated.

To authenticate your application you have to set valid a auth_key and generate a signature using your application auth_secret and receive a session token which you have to in each request to QuickBlox API.

Session token should be sent through HTTP-header called QB-Token. Otherwise, session token can be sent through GET parameters (GET requests) and in POST body (POST requests) via token=... but this way is unsecure.

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. Each API response contains header QB-Token-ExpirationDate which contains session token expiration date.

A session token can be one of 2 types:

  • Application session token (only READ rights)
  • User session token (READ+WRITE rights)

You can create Application session and then upgrade it to User session or you can create User session at once. To create User session you should add users' credentials to create session request. Or you can create Application session and then sign in user.


Access Rights

Roles Resources
Admin panel Access API Access Account Resources
Account owner Yes Yes Read/Write
API Application (application session) No Yes Read
API User (user session) No Yes Read/Write


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 Supported formats Action Description Success HTTP Status Code
/session POST
  • xml
  • json
API Session Creation Or API User Sing In 201
/login POST
  • xml
  • json
API User Sign In 202
/login DELETE
  • xml
  • json
API User Sign Out 200
/session DELETE
  • xml
  • json
API Session Destroy 200
/session GET
  • xml
  • json
API Session Info 200


API Session Creation

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

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

If you have API user login (or email) and password you could authorize user with the same request, just specify login (or email) and password.

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

* 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" \
-d '{"application_id": "2", "auth_key": "DtF9cZPqTF8Wy9Q", "timestamp": "1333630392", "nonce": "1236221330", "signature": "eb0ec2d8c8184a3e62b41da2afb6e8d690577fa4"}' \
https://api.quickblox.com/session.json
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.xml

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
  }
}
<?xml version='1.0' encoding='UTF-8'?>
<session>
  <application-id type='integer'>140</application-id>
  <created-at type='datetime'>2012-04-23T07:50:31Z</created-at>
  <device-id type='integer' nil='true'/>
  <id type='integer'>44315</id>
  <nonce type='integer'>414546828</nonce>
  <token>e472a6a17b19d6cdf95995da62440b861a9b70a4</token>
  <ts type='integer'>1335167303</ts>
  <updated-at type='datetime'>2012-04-23T07:50:31Z</updated-at>
  <user-id type='integer' nil='true'/>
</session>


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
curl -X POST \
-H "QuickBlox-REST-API-Version: 0.1.0" \
-d "application_id=140&auth_key=wJHdOcQSxXQGWx5&timestamp=1326964799&nonce=1392970566&signature=547fc3862220f19768c406f47f30897051794686&user[login]=iostest&user[password]=iostest" \
https://api.quickblox.com/session.xml

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
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<session>
  <application-id type='integer'>140</application-id>
  <created-at type='datetime'>2012-04-23T08:04:20Z</created-at>
  <device-id type='integer' nil='true'/>
  <id type='integer'>44366</id>
  <nonce type='integer'>1392970566</nonce>
  <token>5b5be65d31f22faef77dd2f0a9be8cf0ddf8fc05</token>
  <ts type='integer'>1335167952</ts>
  <updated-at type='datetime'>2012-04-23T08:04:20Z</updated-at>
  <user-id type='integer'>563</user-id>
</session>


API User Sign In

In case of successful authorization, current token will be upgraded to user-level token.

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

* 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"}' \
http://api.quickblox.com/login.json
curl -X POST \
-H "QuickBlox-REST-API-Version: 0.1.0" \
-H "QB-Token: cf5709d6013fdb7a6787fbeb8340afed8aec4c69" \
-d "login=Alisa&password=Alisa" \
http://api.quickblox.com/login.xml

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"
}
<?xml version='1.0' encoding='UTF-8'?>
<user>
  <blob-id type='integer' nil='true'/>
  <created-at type='datetime'>2012-04-13T12:14:22Z</created-at>
  <email nil='true'/>
  <external-user-id type='integer' nil='true'/>
  <facebook-id nil='true'/>
  <full-name nil='true'/>
  <id type='integer'>724</id>
  <last-request-at type='datetime'>2012-04-13T12:29:10Z</last-request-at>
  <login>Alisa</login>
  <phone nil='true'/>
  <twitter-id nil='true'/>
  <twitter-digits-id nil='true'/>
  <updated-at type='datetime'>2012-04-13T12:29:10Z</updated-at>
  <website nil='true'/>
  <tags type='array'/>
</user>


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" \
http://api.quickblox.com/session.json
curl -X DELETE \
-H "QuickBlox-REST-API-Version: 0.1.0" \
-H "QB-Token: 422ce2791d7070b88a82f415b3693c81612e3423" \
https://api.quickblox.com/session.xml

Response

Status: 200, null
Empty body, status: 200


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" \
http://api.quickblox.com/login.json
curl -X DELETE \
-H "QuickBlox-REST-API-Version: 0.1.0" \
-H "QB-Token: 422ce2791d7070b88a82f415b3693c81612e3423" \
http://api.quickblox.com/login.xml

Response

Status: 200, null
Empty body, status: 200


API Session Info

Get info about current session

Request

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

Response

{"_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}
<session>
<_id>541ae90d535cds2e21e000316</_id>
<application-id type="integer">123</application-id>
<created-at type="datetime">2014-09-18T14:15:41Z</created-at>
<device-id type="integer">0</device-id>
<nonce type="integer">1331361499</nonce>
<token>8b75a6c7191285499d890a81df4ee7fe49bc732a</token>
<ts type="integer">1411049740</ts>
<updated-at type="datetime">2014-09-18T14:42:03Z</updated-at>
<user-id type="integer">0</user-id>
<id type="integer">31820</id>
</session>


Examples

PHP

PHP session creation example

Python

Python session creation example

Pascal

Pascal session creation discussion