OAuth - readmill/API GitHub Wiki

This is the documentation for v1 of the Readmill API which is deprecated and will be discontinued on 2012-12-16. Please upgrade to v2, the new developer documentations are at [developers.readmill.com](http://developers.readmill.com).

We use OAuth2 for all authenticated requests. In order to use it you must have an application registered with us. If you want to read up on OAuth2, check OAuth.net or the SoundCloud API Wiki

OAuth 2 requires two endpoints for authorization.

http://readmill.com/oauth/authorize

is used for end user authorization of a client and behaves as specified in Section 3.

http://readmill.com/oauth/token

is used for obtaining an access token and behaves as specified in Section 4

As of today we only support the Authorization code flow which means the following dance. Redirect your app to http://readmill.com/oauth/authorize where your user can choose to allow or deny access to their Readmill account. On deny the user get’s redirected to your redirect url with a flag that says deny, on allow the user get’s redirected back with an authorization code appended to the redirect url. This authorization code is then passed in the call to http://readmill.com/oauth/token where it’s exchanged for an access token and a refresh token.

Point a browser to:

http://readmill.com/oauth/authorize?response_type=code&client_id=acfbd2c5&redirect_uri=http://example.com/callback

This will prompt the user with allow/deny access to account and on allow it will redirect to the following url:

http://example.com/callback?code=acfbd2c5

On deny the user gets redirected to the redirect_uri with an error:

http://example.com/callback?error=user_denied

If you pass in scope=non-expiring, you will get a token that never expires and can ignore the refresh_token flow.

This call will normally return an access token and a refresh token, but if you passed scope=non-expiring (in the authorize step) you will not get a refresh_token and your access_token will never expire.

{
  "access_token":  "04u7h-4cc355-70k3n",
  "expires_in":    3600,
  "scope":         "",
  "refresh_token": "04u7h-r3fr35h-70k3n"
}

Using non-expiring scope:

{
  "access_token":  "04u7h-4cc355-70k3n",
  "expires_in":    3155673599, // = 100 years
  "scope":         "non-expiring"
}

The request token flow is used when the user has an access token that has expired and we don’t want to prompt the user with the allow screen again. This call will return a new access token and a new refresh token.

{
  "access_token":  "04u7h-4cc355-70k3n",
  "expires_in":    3600,
  "scope":         "",
  "refresh_token": "04u7h-r3fr35h-70k3n"
}

To make authenticated requests you send your access token as credentials. You can either send it as a query string:

$ curl http://readmill.com/oauth/echo?access_token=abc123

or as a header

Authorization: OAuth abc123

That’s all you need to authenticate with Readmill