blogg.se's API uses the OAuth 2.0 protocol for simple, but effective authentication and authorization. OAuth 2.0 is much easier to use than previous schemes; developers can start using the blogg.se API almost immediately. The one thing to keep in mind is that all requests to the API must be made over SSL (https:// not http://)
For the most part, blogg.se's API only requires the use of a client_id. A client_id simply associates your server, script, or program with a specific application. However, some requests require authentication - specifically requests made on behalf of a user. Authenticated requests require an access_token. These tokens are unique to a user and should be stored securely. Access tokens may expire at any time in the future.
In order to receive an access_token, you must do the following:
Using the server-side flow is quite easy. Simply follow these steps:
https://api.publishme.se/1/oauth/authorize?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=codeNote: You may provide an optional state parameter to carry through any server-specific state you need to, for example, protect against CSRF issues.
At this point, we present the user with a login screen and then a confirmation screen where they approve your app’s access to his/her blogg.se data.
Once a user successfully authenticates and authorizes your application, we will redirect the user to your redirect_uri with a code parameter that you’ll use in step three.
http://your-redirect-uri?code=CODEIf your request for approval is denied by the user, then we will redirect the user to your redirect_uri with the following parameters:
error: access_denied
error_reason: user_denied
error_description: The user denied your request
http://your-redirect-uri?error=access_denied&error_reason=user_denied&error_description=The+user+denied+your+requestIt is your responsibility to fail gracefully in this situation and display a corresponding error message to your user.
In the previous step, you'll have received a code which you'll have to exchange in order to receive an access_token for the user. In order to make this exchange, you simply have to POST this code, along with some app identification parameters to our access_token endpoint. Here are the required parameters:
For example, you could request an access_token like so:
curl \-F 'client_id=CLIENT-ID' \
-F 'client_secret=CLIENT-SECRET' \
-F 'grant_type=authorization_code' \
-F 'redirect_uri=YOUR-REDIRECT-URI' \
-F 'code=CODE' \
https://api.publishme.se/1/oauth/access_token
If successful, this call will return a neatly packaged OAuth Token that you can use to make authenticated calls to the API. We also include the user who just authenticated for your convenience:
{
"access_token": "u3LEfO0CwkcIlhniei14fRhggDYTdeNImNf6xTNp69QyWdzV",
}Note that we do not include an expiry time. Our access_tokens have no explicit expiry, though your app should handle the case that either the user revokes access or we expire the token after some period of time. In this case, your response's meta will contain an "error_type=OAuthAccessTokenError";. In other words: do do not assume your access_token is valid forever.
If you're building an app that does not have a server component (a purely javascript app, for instance), you'll notice that it’s impossible to complete step three above to receive your access_token without also having to ship your client secret. You should never ship your client secret onto devices you don’t control. Then how do you get an access_token? Well the smart folks in charge of the OAuth 2.0 spec anticipated this problem and created the Implicit Authentication Flow.
https://api.publishme.se/1/oauth/authorize?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=token
At this point, we present the user with a login screen and then a confirmation screen where they approve your app’s access to their blogg.se data. Note that unlike the explicit flow the response type here is "token";.
Once the user has authenticated and then authorized your application, we’ll redirect them to your redirect_uri with the access_token in the url fragment. It’ll look like so:
http://your-redirect-uri#access_token=ACCESS-TOKEN
Simply grab the access_token off the URL fragment and you’re good to go. If the user chooses not to authorize your application, you’ll receive the same error response as in the explicit flow
{access_token: String}