docs.pushbullet.comPushbullet API

APPS CHANNELS BLOG API HELP Pushbullet’s API enables developers to build on the Pushbullet infrastructure. Our goal is to provide a full API that enables anything to tap into the Pushbullet network. This is important to us becauseor your app. Here’s roughly how this looks with pictures: Getting Started To get started, create a client (register your application) on the Create Client page. For the examples on this page, the client looks like this: EXAMPLE CLIENT { "client_id" : "YW7uItOzxPFx8vJ4" , "client_secret" : "MmA98EDg0pjr4fZw" , "iden" : "ujpah72o0sjAoRtnM0jc" , "image_url" : "http://www.catpusher.com/logo.png" , "name" : "Cat Pusher" , "redirect_uri" : "http://www.catpusher.com/auth_complete" , "website_url" : "http://www.catpusher.com" } Getting an Access Token Once you’ve created a client, you can send a user to https://www.pushbullet.com/authorize with the following parameters: client_id - client_id from registering your client redirect_uri - The url you want to redirect the user to after authorization is complete. The path portion must match what was provided for the client, the query string may be set dynamically. response_type - Either "code" (if you’ve got a server) or "token" (if your app is entirely on the client) EXAMPLE URL https://www.pushbullet.com/authorize?client_id=YW7uItOzxPFx8vJ4&redirect_uri=http%3A%2F%2Fwww.catpusher.com%2Fauth_complete&response_type=code NOTE: There’s an example url ("oauth test url") on the Create Client page for your app. When the user is sent to this page, they are able to authorize or deny your application. If they choose deny, they get redirected to the redirect_uri with the parameter "error=access_denied". If they chose authorize, there are two possible next steps, depending on the value of response_type: For Client-Side Apps: response_type=token The user is redirected to the redirect_uri with a url fragment of "access_token=access_token". If you have a client side app running an embedded web browser, you can configure your redirect_uri to be "https://www.pushbullet.com/login-success" and then use this redirect_uri in the authorize call. EXAMPLE URL https://www.pushbullet.com/authorize?client_id=YW7uItOzxPFx8vJ4&redirect_uri=https%3A%2F%2Fwww.pushbullet.com%2Flogin-success&response_type=token EXAMPLE REDIRECT https://www.pushbullet.com/login-success#access_token=o.RUe7IZgC6384GrI1 For Apps with Servers: response_type=code If you have a server you can use this response_type, it’s potentially more secure than the client-side one, since the client never sees the actual access token. In this mode the user is redirected to the redirect_uri with a parameter "code=code". EXAMPLE URL https://www.pushbullet.com/authorize?client_id=YW7uItOzxPFx8vJ4&redirect_uri=http%3A%2F%2Fwww.catpusher.com%2Fauth_complete&response_type=code EXAMPLE REDIRECT http://www.catpusher.com/auth_complete?code=RUe7IZgC6384GrI1 Your server then peforms a POST request to https://api.pushbullet.com/oauth2/token with the following parameters: grant_type - Set to "authorization_code" client_id - client_id from registering your client client_secret - client_secret from registering your client code - code from the redirect Example: Convert Code to Access Token Request curl header ’Access-Token: your_access_token_here’ \ header ’Content-Type: application/json’ \ data-binary ’{"client_id":"YW7uItOzxPFx8vJ4","client_secret":"MmA98EDg0pjr4fZw","code":"RUe7IZgC6384GrI1","grant_type":"authorization_code"}’ \ request POST \ https://api.pushbullet.com/oauth2/token Response { "access_token" : "a6FJVAA0LVJKrT8k" , "token_type" : "Bearer" } You can add extra query params to the end of redirect_uri if you need to store extra state for the request. For instance, if you have your client’s redirect_uri set to http://www.catpusher.com/auth_complete , then when you build the url to send the user to Pushbullet, you could specify redirect_uri=http://www.catpusher.com/auth_complete?state=zhk2KJ3SAAS3q1 . When the user finishes authorizing your app, they would end up at http://www.catpusher.com/auth_complete?state=zhk2KJ3SAAS3q1&code=RUe7IZgC6384GrI1 . Using Your Access Token Now that you have an access token, you can access Pushbullet as that user. Just include the access_token with your requests as the username in HTTP Basic Auth or set the Access-Token header to your access_token . Make sure to keep the access_token in a safe place, it allows access to your users accounts! Example: Get Current User Request curl header ’Access-Token: your_access_token_here’ \ https://api.pushbullet.com/v2/users/me Response { "created" : 1381092887.398433 , "email" : " [email protected] " , "email_normalized" : " [email protected] " , "iden" : "ujpah72o0" , "image_url" : "https://static.pushbullet.com/missing-image/55a7dc-45" , "max_upload_size" : 26214400 , "modified" : 1441054560.741007 , "name" : "Elon Musk" } The access_token does not have a set expiration time, but may be expired at some point in the future. If you delete your client, all existing tokens are invalidated. End-to-End Encryption We support end-to-end encryption for Notification Mirroring, Universal Copy & Paste, and SMS . We use client-side symmetric encryption for this. No keys are ever sent to the server, not even public keys, which is especially nice from a security standpoint. The encryption is used primarily for ephemerals . If you enable it in your Pushbullet client, you should be able to see the encrypted messages on the stream whenever you use any of the features that support end-to-end encryption. Key Generation The key is created from a user-supplied password and passed through PBKDF2 : Pseudorandom function: HMAC-SHA256 Password: password supplied by the user for encryption, must be the same on all Pushbullet devices owned by the user Salt: the user iden for the current user, e.g. up0snaKOsn Number of iterations: 30,000 Derived key length: 256-bit Code Sample: Generate an Encryption/Decryption Key This example uses the javascript Forge library var pseudorandom_function = forge . md . sha256 . create ( ) ; var password = "hunter2" ; var salt = "up0snaKOsn" ; var iterations = 30000 ; var derived_key_length_bytes = 32 ; // 256-bit var key = forge . pkcs5 . pbkdf2 ( password , salt , iterations , derived_key_length_bytes , pseudorandom_function ) // encode to base64 so we can easily print the key // (normally it’s in binary and can’t be printed) var base64_key = btoa ( key ) ; console . log ( "base64_key:" , base64_key ) ; Encryption To encrypt a message, use AES-256 with GCM Authentication . AES-256 uses the 256-bit key that is output by PBKDF2. To encrypt you need to generate a 96-bit initialization vector (this is used to start the encryption process, it is not a secret). The output of AES-256 with GCM will be the encrypted message (arbitrary length) and a 128-bit tag. The encoding for this encrypted message looks like this: encoded_message = "1" + tag + initialization_vector + encrypted_message The 1 prefix is a version number indicating the version of the encoding. When encoded_message is put into JSON, it must be base64-encoded since JSON cannot handle binary data. Code Sample: Encrypt a Message This example uses the javascript Forge library // convert key from base64 to binary var key = atob ( "1sW28zp7CWv5TtGjlQpDHHG4Cbr9v36fG5o4f74LsKg=" ) ; var initialization_vector = forge . random . getBytes ( 12 ) ; // 96-bit var message = "meow!" ; var cipher = forge . cipher . createCipher ( ’AES-GCM’ , key ) ; cipher . start ( { "iv" : initialization_vector } ) ; cipher . update ( forge . util . createBuffer ( forge . util . encodeUtf8 ( message ) ) ) ; cipher . finish ( ) ; var tag = cipher . mode . tag . getBytes ( ) ; var encrypted_message = cipher . output . getBytes ( ) ; var encoded_message = "1" + tag + initialization_vector + encrypted_message ; var base64_encoded_message = btoa ( encoded_message ) ; console . log ( "base64_encoded_message:" , base64_encoded_message ) ; Decryption If you can...