OAuth Procedure

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!

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

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

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 as parameter.

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.