OAuth Procedure

Flattr uses OAuth 2 to give access to user accounts through the REST API. flattr4j offers a package to make the OAuth procedure as easy as possible for you. Core of the package is the class org.shredzone.flattr4j.oauth.FlattrAuthenticator.

1: Retrieve an Application Key

First of all, your application needs to be registered with Flattr. The registration form speaks for itself.

Flattr needs a callback URL to send a validation code to. The user will be forwarded to this URL after authentication, so you will need to offer a servlet that handles the callback.

After you have registered your application, a consumer key and a consumer secret is shown to you. Save these codes, as they will later identify your application at Flattr. You will only need to register your application once.

2: Retrieve a Request Token

Allright, now a Flattr user wants to give your application access to his Flattr account. The first step is to retrieve the Flattr URL to forward the user to. At this stage, you have to decide what privileges (called "scope") you need from the Flattr user. There is an enumeration of all available scopes and their meaning at org.shredzone.flattr4j.oauth.Scope. Also, all methods of the FlattrService are annotated with the required scopes.

You also need to set the callback URL you have registered with Flattr in the first step, by using setCallbackUrl(). This URL must exactly match the URL you gave at registration, otherwise the authentication process will fail!

In order to reidentify your user when he is forwarded to the callback URL, you can also pass a unique identifier (like a user ID) to authenticate(). This identifier - called state - will be returned as a parameter of the callback URL.

Now you invoke the FlattrAuthenticator like this:

String APP_KEY = <your consumer key>;
String APP_SECRET = <your consumer secret>;
String CALLBACK_URL = <your callback url>;
String STATE = <your unique user identifier>;

FlattrAuthenticator auth = new FlattrAuthenticator(APP_KEY, APP_SECRET);
auth.setCallbackUrl(CALLBACK_URL);
auth.setScope(EnumSet.of(Scope.FLATTR, Scope.THING));
String url = auth.authenticate(STATE);

System.out.println("Please visit: " + url);

In this example, flattr and thing scopes are requested.

In the last line, a URL is presented to the user. This is a link to the Flattr site. The user will need to log in with his Flattr credentials there. After that, your application registration (from step 1) is shown to him, along with the requested scopes. The user can now accept or deny the request to get access to his Flattr account.

When the user accepts, a validation code is generated by Flattr, and your callback URL is invoked with the code and (optionally) your state as parameters.

3: Retrieve an Access Token

In a final step, the access token is retrieved:

String APP_KEY = <your consumer key>;
String APP_SECRET = <your consumer secret>;
String CODE = <the validation code>;

FlattrAuthenticator auth = new FlattrAuthenticator(APP_KEY, APP_SECRET);
AccessToken token = auth.fetchAccessToken(CODE);

String ACCESS_TOKEN = token.getToken();

The access token needs to be stored somewhere in your application. You will need it to access the user's Flattr account by the REST API. The token remains valid until the user revokes it.

The validation code can now be discarded. The Flattr server would not accept it again, so there is no further use for it.

The authorization process is completed now.

4: Client authentication

The authentication process mentioned above requires a callback URL. However, sometimes you cannot provide a callback URL, for example on standalone desktop applications.

OAuth v1 offered a so-called "out-of-band" authentication, which was supported as "Client" mode on an early Flattr API. This authentication style is not available any more, which makes authentication of standalone software somewhat difficult.

A possible solution is to register an URL with your OS (e.g. "flattr4j://your-app-name") and bind it to your application. Then register this URL as callback URL with Flattr. The login and authentication is then performed in a browser window. After successful authentication, Flattr will forward to your URL, and your OS will invoke your application, giving the authenticate attribute embedded in the parameter. I confess, this is tough to implement in Java and in a platform-independent manner.

There is a separate chapter about how to authenticate Android apps.