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 10 minutes. Please, be aware about it. 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	Web Access	API Access	Account Resources	API Users	Other Accounts Resources Access	Self Created Resources
Account Users	Yes	No	Read/Write	Read/Write	No	Full
API Application	No	Yes	Read	Create	No	No
API Users	No	Yes	Read	No	No	Full

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', fused 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: 'app_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
/auth	POST	xml json	API Session Creation Or API User Sing In	201
/users/authenticate	POST	xml json	API User Sign In	202
/auth_exit	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	a0b03a2bfe32117aa805ee36d6e87f970097e341	HMAC code from request parameters. It also includes Authentication Secret.

If you have API user login and password you could authorize user with the same request, just specify login password and owner_id as additional extended parameters.

Extended Set Of Request Parameters
Param	Required	Type	Value Example	Description
user[login]	Yes	String	bukster	API User login
user[password]	Yes	String	bad-as-passwd	API User password
user[owner_id]	Yes	Integer	2	API User owner identifier

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	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 -d "application_id=140&auth_key=7quWEh-k6TqghXe&timestamp=1326964049&nonce=414546828&signature=e6e603c251a569e70a2f27a8c71b5017e81e05d5" https://api.quickblox.com/auth.xml

curl -X POST -H "Content-Type: application/json" -d '{"application_id": "2", "auth_key": "DtF9cZPqTF8Wy9Q", "timestamp": "1333630392", "nonce": "1236221330", "signature": "eb0ec2d8c8184a3e62b41da2afb6e8d690577fa4"}' https://api.quickblox.com/auth.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 -d "application_id=140&auth_key=wJHdOcQSxXQGWx5&timestamp=1326964799&nonce=1392970566&signature=547fc3862220f19768c406f47f30897051794686&user[login]=iostest&user[password]=iostest&user[owner_id]=4360" https://api.quickblox.com/auth.xml

curl -X POST -H "Content-Type: application/json" -d '{"application_id": "2", "auth_key": "DtF9cZPqTF8Wy9Q", "timestamp": "1333630580", "nonce": "1340569516", "signature": "13293a5bd2026b957ebbb36c89d9649aae9e5503", "user": {"login": "injoit", "password": "injoit", "owner_id": "4"}}' https://api.quickblox.com/auth.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 -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&user[owner_id]=4" https://api.quickblox.com/auth.xml

curl -X POST -H "Content-Type: application/json" -d '{"application_id": "2", "auth_key": "DtF9cZPqTF8Wy9Q", "timestamp": "1336488307", "nonce": "855029415", "signature": "e8d8b7e768f487a9f422063c6addef6e0bc58023", "user": {"login": "injoit", "password": "injoit", "owner_id": "4"}, "device": {"platform": "ios", "udid": "7847674035" }}' https://api.quickblox.com/auth.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	Yes	String	mylogin	API User login
password	Yes	String	mypassword	API User password
owner_id	Yes	Integer	3	ID of user owner

Request

curl -X POST -d "login=Alisa&password=Alisa&owner_id=4&token=b284ddf44f5369611fe14e0e588f1cfa855116c8" http://api.quickblox.com/users/authenticate.xml

curl -X POST -H "Content-Type: application/json" -d '{"login": "injoit", "password": "injoit", "owner_id": "4", "token": "cf5709d6013fdb7a6787fbeb8340afed8aec4c69"}' http://api.quickblox.com/users/authenticate.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 "https://api.quickblox.com/auth_exit.xml?token=422ce2791d7070b88a82f415b3693c81612e3423"

curl -X DELETE "http://api.quickblox.com/auth_exit.json?token=8b75a6c7191285499d890a81df4ee7fe49bc732a"

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