Friendica API authentication

You can authenticate requests to the Friendica API via two methods: HTTP Basic and OAuth.

HTTP Basic is easy to use, but it requires your account password, so it grants complete access to your account.

OAuth is significantly more involved, but has the ability to grant limited permissions, so that someone can use the API to e.g. read your posts, but not create new ones. You can therefore use OAuth with other applications that you wouldn't want to trust with your entire account.

Hopefully any existing guide to HTTP Basic authentication should be sufficient here. Use the same username and password you use to login.

One wrinkle is that if you have two-factor authentication enabled (which is a good idea!) you'll likely need to create an “app-specific password” to bypass 2fa for this one use case. You can do this from the 2fa settings pane. (This weakens the protection of 2fa, since if someone manages to steal the app-specific password, they can use it to access your account. It is at least a randomly-generated password that you don't routinely enter into web browsers, so it's a little harder to steal than your account password, but still, be careful.)

This doc is cobbled together after I worked out this process myself, so beware of inaccuracies. OAuth is a security mechanism, so getting this process wrong can expose your users' accounts to being impersonated or their data stolen. Be careful.

Also, try not to get confused between Friendica as an OAuth client versus Friendica as an OAuth provider. As a client, Friendica addons can log in to other services to allow Friendica to take actions on them (e.g. send your Friendica posts to Tumblr or whatever). As a provider, Friendica can allow non-Friendica apps to ask permission to take actions on behalf of your Friendica account. Most of the existing “Friendica OAuth” search results seem to be about Friendica as a client, but this article is about Friendica as a provider.

Friendica supports OAuth 1 and not OAuth 2 (see github issue), but they are very similar. The process is complicated, but it's worth it for some use cases.

The user experience is the same as e.g. those “Login with Google” or “Login with GitHub” buttons you see around the web. Some application wants your Friendica instance to confirm that you have an account with them, or wants to take some actions on your Friendica account. You click the button on their website, it takes you to your Friendica instance, where you can choose whether to share your identity with the original website, and if you do, you're sent back there logged in, having granted them permission to do whatever they asked you for.

For the sake of example, let's suppose you have a web application called FarmGame hosted at https://farmgame.example, and you want to allow users of a Friendica instance called FriendZone, hosted at https://friendzone.example, to log in to your app and let your app post to their timelines.

To set this up, you need FriendZone to give you a “client ID” (which your users use to tell FriendZone who you are) and a “client secret” (which is only used for direct communications between you and FriendZone, users don't see it).

Client IDs and client secrets are stored in the application table in Friendica. There's no user-facing way to modify this table, it can only be done with addons, e.g. oauthprovider. You'll see you also need to specify a “redirect URI”, which is where Friendica sends your user back to with your token, and “scopes”, which is a space-separated list of permissions. (The database schema has scopes as optional, but I think you can't actually complete the process if scopes are NULL).

The whole process looks like this:

1. FriendZone adds an entry to their application table, with a randomly-generated client_id and client_secret, and a redirect_uri as specified by FarmGame (for the sake of example, let's say https://farmgame.example/complete-friendica-login).
2. When FarmGame users click their “login with FriendZone” link, it takes them to https://friendzone.example/oauth/authorize?client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI&response_type=code&state=$STATE, where:
   • $CLIENT_ID and $REDIRECT_URI match what's in the application table (urlencoded if necessary),
   • $STATE is a new random string, which the FarmGame server remembers (e.g. it sends the client a session ID cookie and then stores a mapping from session ID to state).
3. https://friendzone.example/oauth/authorize shows the user a prompt. If they accept, it redirects them to https://farmgame.example/complete-friendica-login?code=$CODE&state=$NEWSTATE. FarmGame checks that $NEWSTATE matches the $STATE it stored earlier, to confirm that this really is a user coming back from their login page.
4. FarmGame sends a HTTP POST request to https://friendzone.example/oauth/token, specifying in the request body:
   • client_id, client_secret and redirect_uri matching its application record,
   • the code it just got from the user,
   • grant_type=authorization_code
5. FarmGame receives a JSON object from FriendZone in reply. The object has a few different keys, but the most important ones are me, which tells FarmGame your profile link (and therefore your identity), and access_token, which FarmGame can then use in an Authorization: Bearer $access_token HTTP header to authorize further API requests.

If for whatever reason you can't make the above process work for you, you can also specify redirect_uri as urn:ietf:wg:oauth:2.0:oob. Then when you confirm with Friendica that the app is authorized, instead of redirecting you back to the app, Friendica will just display the code, which you can then enter into the app manually.