Authentication

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://)

Do you need to authenticate?

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.

Receiving an access_token

In order to receive an access_token, you must do the following:

  1. Direct the user to our authorization url.
    • If the user is not logged in, they will be asked to log in.
    • The user will be asked if they'd like to give your application access to his/her Blogg.se data.
  2. The server will redirect the user in one of two ways that you choose:
    • Server-side flow (recommended):Redirect the user to a URI of your choice. Take the provided code parameter and exchange it for an access_token by POSTing the code to our access_token url.
    • Implicit flow: Instead of handling a code, we include the access_token as a fragment (#) in the URL. This method allows applications without any server component to receive an access_token with ease.

Server-side (Explicit) Flow

Using the server-side flow is quite easy. Simply follow these steps:

Step One: Direct your user to our authorization URL

https://api.publishme.se/1/oauth/authorize?client_id=CLIENT-ID&redirect_uri=REDIRECT-URI&response_type=code

Note: 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.

Step Two: Receive the redirect from Blogg.se

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=CODE

If 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+request

It is your responsibility to fail gracefully in this situation and display a corresponding error message to your user.

Step Three: Request the access_token

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:

  • client_id: your client id
  • client_secret: your client secret
  • grant_type: authorization_code is currently the only supported value
  • redirect_uri: the redirect_uri you used in the authorization request. Note: this has to be the same value as in the authorization request.
  • code: the exact code you received during the authorization step.

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.

Client-Side (Implicit) Authentication

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.

Step One: Direct your user to our authorization URL

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";.

Step Two: Receive the access_token via the URL fragment

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



Oauth signup dialog

POST,GET https://api.publishme.se/1/oauth/authorize_signup

Description
Signup page for oauth

This is a server-to-server API and includes secrets and therefore MAY never
be used outside a secure connection.

This page requires that the API key has the signup-privilege

GET PARAMETERS
client_id The API-key for your app. required
redirect_uri The URI to redirect to after authentication required
response_type either code for server side flow or token for implicit flow required
state random string to protect against CSRF issues optional

RETURNS
A signup form to be presented to the user, upon signup completion or cancellation user is returned to redirect_uri
Access token

POST,GET https://api.publishme.se/1/oauth/access_token

Description
Grant an access token from code given in authorization

This is a server-to-server API and includes secrets and therefore MAY never
be used outside a secure connection.

GET/POST PARAMETERS
client_id The API-key for your app. required
client_secret The API-secret for your app. required
redirect_uri The same URI used in the user authentication required
grant_type authorization_code is currently the only supported valuerequired
code The code previouly returned from the user authentication required

RETURNS
{access_token: String}
Oauth authorize dialog

POST,GET https://api.publishme.se/1/oauth/authorize

Description
Display authorization page for oauth

This is a server-to-server API and includes secrets and therefore MAY never
be used outside a secure connection.

GET PARAMETERS
client_id The API-key for your app. required
redirect_uri The URI to redirect to after authentication required
response_type either code for server side flow or token for implicit flow required
state random string to protect against CSRF issues optional

RETURNS
A authentication form to be presented to the user, upon authentication or cancellation user is returned to redirect_uri