Getting Started

Here you may find instructions and necessary procedures to follow to get you started.

Authentication and Access

The put.io API can only be accessed via OAuth 2.0. This is really important to help us track usage of the API by your applications while keeping our users’ data safe. It’s a standard used by various large API providers, including the Facebook Graph API.

1. Sign Up

Start by registering your application and obtaining your API credentials. You may want to sign up under a separate account with an extra-secure password to own these credentials. Since each credential is tied to a particular URL, you may want to create a set of development credentials which point to your development server URL, and production credentials which point to your production server URL. For the purposes of OAuth, your “key” from that registration process is your “id” here, and your secret from registering is your secret here.

2. Obtain an Access Token (OAuth Token)

There are three general ways to use our new API.

  • Web server application

(Python, Go, Java, etc.)

  • Redirect users who wish to authenticate to
https://api.put.io/v2/oauth2/authenticate
    ?client_id=YOUR_CLIENT_ID
    &response_type=code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
  • If a user accepts, they will be redirected back to
https://YOUR_REGISTERED_REDIRECT_URI/?code=CODE
  • Your server will make a request for
https://api.put.io/v2/oauth2/access_token
    ?client_id=YOUR_CLIENT_ID
    &client_secret=YOUR_CLIENT_SECRET
    &grant_type=authorization_code
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
    &code=CODE
  • The response will be JSON
{
    'access_token': ACCESS_TOKEN
}
  • Pure AJAX Application

(Javascript)

  • Redirect users who wish to authenticate to
https://api.put.io/v2/oauth2/authenticate
    ?client_id=CLIENT_ID
    &response_type=token
    &redirect_uri=YOUR_REGISTERED_REDIRECT_URI
  • If a user accepts, they will be redirected back to
http://YOUR_REGISTERED_REDIRECT_URI/#access_token=ACCESS_TOKEN
  • Phone-based or client-side application

(Android, iOS, etc.)

  • If you have no substantive server code, you can embed a web browser and use the token flow, redirecting the user to a dummy page on your domain. You can then grab the token off of the URL and close the browser.
  • If you have a server as part of your application, you can use the server flow above, possibly in an embedded browser.
  • An alternative to the above is to use the server flow and an external browser, but redirect to a custom URI handler that brings the user back to our application. You can embed the secret in your application and exchange the provided code for an access token. PLEASE take steps to obfuscate your client secret if you include it in released code, and be prepared to rotate it if needed.

3. Make Requests

Once you have an access token. It’s easy to use any of the endpoints, by just adding oauth_token=ACCESS_TOKEN to your GET or POST request. For example, from the command line, you can do

$ curl -H 'Accept: application/json' https://api.put.io/v2/files/list?oauth_token=ACCESS_TOKEN
Pow! That’s all there is to it. Few things to point out:
  • Make sure you are sending the header “Accept: application/json” when making a request.
  • If the request method is POST, parameters should be urlencoded, not JSON.

Notes on OAuth

  • OAuth can pass secrets in the clear without requiring manual signing of requests. The catch is that all requests must be via HTTPS, and you’ll see errors when not using HTTPS.
  • The examples above use /authenticate instead of /authorize. Following precedent established by Twitter and LinkedIn, /authenticate handles both user authentication and app authorization and will automatically redirect if a user has already authorized the calling page. This is useful if the user is already logged in and has authorized your app and needs to reestablish the OAuth Token bypassing the log-in and authorization process.
  • Although at this time we do not expire OAuth access tokens, you should be prepared for this possibility in the future. Also remember that a user may revoke access via the put.io settings page at any time. Using /authorize will ask the user to re-authenticate their identity and reauthorize your app while giving the user the option to login under a different account.

Responses and Errors

  • All successfull responses will look roughly like
{
  "status": "OK",
  ...response...
}
  • All error responses will look roughly like
{
  "status": "ERROR",
  "error_type": ...,
  "error_message": ...
}

Errors will usually include an error_type field about what went wrong, intended for the developer. In some cases, the server may include an error_message, which is a string intended for the client to display back to the user directly.

CORS

Cross-origin resource sharing (CORS) is a mechanism that allows a web page to make XMLHttpRequests to another domain. The API supports CORS for AJAX requests from any origin. All API responses include following header:

Access-Control-Allow-Origin: "*"

API Clients

We have Python and Go clients at the moment.