Obtaining client app access

Authentication and authorization

Up until this point, we’ve been working with publicly available information, but not all information is public. Some information requires permission before viewing it, in order to audit who is requesting that information (and to potentially revoke or deny access).

This is where OAuth comes in. OAuth is a mechanism for generating access tokens that can be used to authenticate (verify) that a request is coming from a specific client, and ensure that the requested action is authorized (allowed) by the server’s access control policies.

Creating our application

The first thing we will need to do is to register an application, in order to be able to generate access tokens later. The application can be created like so:

curl -X POST \
	-F 'client_name=Test Application' \
	-F 'redirect_uris=urn:ietf:wg:oauth:2.0:oob' \
	-F 'scopes=read write push' \
	-F 'website=https://myapp.example' \
	https://mastodon.example/api/v1/apps

In the above example, we specify the client name and website, which will be shown on statuses if applicable. But more importantly, note the following two parameters:

• redirect_uris has been set to the “out of band” token generation, which means that any generated tokens will have to be copied and pasted manually. The parameter is called redirect_uris because it is possible to define more than one redirect URI, but when generating the token, we will need to provide a URI that is included within this list.
• scopes allow us to define what permissions we can request later. However, the requested scope later can be a subset of these registered scopes. See OAuth Scopes for more information.

You can also create applications by POSTing a JSON body to the same endpoint, as documented in POST /api/v1/apps.

We should see a CredentialApplication entity returned, but for now, we only care about client_id and client_secret.

The client_id and client_secret values will be used to generate access tokens, so they should be cached for later use. See POST /api/v1/apps for more details on registering applications.

Example authentication code flow

Now that we have an application, let’s obtain an access token that will authenticate our requests as that client application. To do so, use POST /oauth/token like so:

curl -X POST \
	-F 'client_id=your_client_id_here' \
	-F 'client_secret=your_client_secret_here' \
	-F 'redirect_uri=urn:ietf:wg:oauth:2.0:oob' \
	-F 'grant_type=client_credentials' \
	https://mastodon.example/oauth/token

Note the following:

• client_id and client_secret were provided in the response text when you registered your application.
• redirect_uri must be one of the URIs defined when registering the application.
• We are requesting a grant_type of client_credentials, which defaults to giving us the read scope.

The response of this method is a Token entity. We will need the access_token value. Once you have the access token, save it in your local cache.

To use it in requests, add the HTTP header Authorization: Bearer <access_token> to any API call that requires OAuth (i.e., one that is not publicly accessible).

Let’s verify that our obtained credentials are working by calling GET /api/v1/apps/verify_credentials:

curl \
	-H 'Authorization: Bearer <access_token>' \
	https://mastodon.example/api/v1/apps/verify_credentials

If we’ve obtained our token and formatted our request correctly, we should see our details returned to us as an Application entity (without the client_secret property).

What we can do with authentication

With our authenticated client application, we can view relations of an account with GET /api/v1/accounts/:id/following and GET /api/v1/accounts/:id/followers. Also, some instances may require authentication for methods that would otherwise be public, so if you encountered any authentication errors while playing around with public methods, then those methods should now work.

Last updated October 10, 2024 · Improve this page