QuickBlox Developers (API docs, code samples, SDK)

From QuickBlox Developers (API docs, code samples, SDK)

Jump to: navigation, search

Summary

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

There are to ways to access QuickBlox API interface as API Application and as API User. The way the API is accessed effects the set of allowed actions. For details about Access Right look at table below.

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 should use to send requests to QuickBlox API. After receiving your session token API application can get READ access to Account information and registered API User. API application after receiving session token can not send signed requests until this token is valid.

Expiration time for token is 2 hours. Please, 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 session.

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), but these ways are unsecure and deprecated.

After registration, the API User using his username and password must log in with this credentials to upgrade his session from API Application level to API User.

After login, user must have READ permission to all data of Account and created a new Resources.

Need to know information

Before using Authentication and Authorization API please read the following:

Access Rights


Roles	Resources
Roles	Admin panel Access	API Access	Account Resources	API Users	Other Accounts Resources Access	Self Created Resources
Account Users	Yes	Yes	Read/Write	Read/Write	No	Full
API Application	No	Yes	Read	Read/Create	No	No
API Users	No	Yes	Read	Read/Create	No	Full

Signature generation

HMAC-SHA function of the body of the request, with a key Authentication 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[id]=123 is used just such a line of user[id]=123

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

Authentication and Authorization API

Requests and Responses

Make sure that you set the token parameter for all requests to the API interface except the request to /auth.


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

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 10 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	Refer to Social Networks Integration Manual
scope	Optional	String	friends_status,read_mailbox,photo_upload	A List of permission required for Facebook application. See Facebook docs: Permission
keys[token]	Optional	String	AM46dxjhisdffgry26282352fdusdfusdfgsdf	Social network provider's access token
keys[secret]	Optional	String	t35400dfzxcxvsdfn76gancHDHoad7a7fs	Social network provider's access token secret (need only for Twitter)

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

Deprecated: You no longer need to use Device parameters
If you could retrieve push notifications - just specify device[platform] and device[udid] as additional extended parameters.

Extended Set Of Request Parameters
Param	Required	Type	Value Example	Description
device[platform]	Optional	String	ios, android, windows_phone, blackberry	Platform of device, which is the source of API requests to Quickblox
device[udid]	Optional	String	2343af3433aa3a4fsvsa1321321	UDID (Unique Device identifier) of device, which is the source of API requests to Quickblox. Required only if device[platform] received.

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

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

Response

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

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

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

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

{
  "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
  }
}

With Device parameters

Request

curl -X POST \
-H "QuickBlox-REST-API-Version: 0.1.0" \
-d "application_id=2&auth_key=DtF9cZPqTF8Wy9Q&device[platform]=ios&device[udid]=aa5238fa95848f6bb15501c74f5641d997e0100&nonce=918397594&signature=5f94b95112302e61fc2c388545bcb4e298bf3329&timestamp=1337161856&user[login]=Sun&user[password]=Sun" \
https://api.quickblox.com/session.xml

curl -X POST 
-H "Content-Type: application/json"
-H "QuickBlox-REST-API-Version: 0.1.0" \
-d '{"application_id": "2", "auth_key": "DtF9cZPqTF8Wy9Q", "timestamp": "1336488307", "nonce": "855029415", "signature": "e8d8b7e768f487a9f422063c6addef6e0bc58023", "user": {"login": "injoit", "password": "injoit"}, "device": {"platform": "ios", "udid": "7847674035" }}' \
https://api.quickblox.com/session.json

Response

<?xml version="1.0" encoding="UTF-8"?>
<session>
  <application-id type='integer'>2</application-id>
  <created-at type='datetime'>2012-05-16T09:52:05Z</created-at>
  <device-id type='integer'>57</device-id>
  <id type='integer'>2542</id>
  <nonce type='integer'>918397594</nonce>
  <token>e5b605850d37d8dd7f2597ffae8b7a525c06536d</token>
  <ts type='integer'>1337161856</ts>
  <updated-at type='datetime'>2012-05-16T09:52:05Z</updated-at>
  <user-id type='integer'>797</user-id>
</session>

{
  "session": {
    "application_id": 2,
    "created_at": "2012-04-03T08:03:47Z",
    "device_id": 71,
    "id": 753,
    "nonce": 345065630,
    "token": "eeccbf25a867a7b05803105da4d2cffaa5ec50c2",
    "ts": 1333438850,
    "updated_at": "2012-04-03T08:03:47Z",
    "user_id": 3
  }
}

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	Refer to Social Networks Integration Manual
scope	Optional	String	friends_status,read_mailbox,photo_upload	A List of permission required for Facebook application. See Facebook docs: Permission
keys[token]	Optional	String	AM46dxjhisdffgry26282352fdusdfusdfgsdf	Social network provider's access token
keys[secret]	Optional	String	t35400dfzxcxvsdfn76gancHDHoad7a7fs	Social network provider's access token secret (need only for Twitter)

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

Request

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

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

Response

<?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>
  <owner-id type='integer'>4</owner-id>
  <phone nil='true'/>
  <twitter-id nil='true'/>
  <updated-at type='datetime'>2012-04-13T12:29:10Z</updated-at>
  <website nil='true'/>
  <tags type='array'/>
</user>

{
  "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",
  "owner_id": 4,
  "phone": null,
  "twitter_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: 422ce2791d7070b88a82f415b3693c81612e3423" \
https://api.quickblox.com/session.xml

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

Response

Empty body, status: 200

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: 422ce2791d7070b88a82f415b3693c81612e3423" \
http://api.quickblox.com/login.xml

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

Response

Empty body, status: 200

Status: 200, null

QuickBlox Developers (API docs, code samples, SDK)

Authentication and Authorization

Contents

Summary

Need to know information

Access Rights

Signature generation

Authentication and Authorization API

Requests and Responses

API Session Creation

Parameters

Request

Response

With User authorization

Request

Response

With Device parameters

Request

Response

API User Sign In

Parameters

Request

Response

API Session Destroy

Parameters

Request

Response

API User Sign Out

Parameters

Request

Response