Authentication Flows

To authenticate you will need an access token from the fediverse instance you are connecting to. Minimal-activitypub supports two different ways of generating access tokens. One requires that the Username and password is supplied, the other generates an Authorization URL that a user needs to visit to generate an authorization code that then needs to be supplied to minimal-activitypub to ultimately generate an access token.

Username and password

The sample code below shows the steps needed to generate an access token with having a user visit a URL and then input the authorization code provided on that URL to ultimately generate an access token.

 1from minimal_activitypub.client_2_server import ActivityPub
 2from httpx import AsyncClient
 3
 4async def get_access_token(mastodon_domain, user_name, password):
 5
 6   async with AsyncClient(http2=True) as client:
 7      # Create app
 8      client_id, client_secret = await ActivityPub.create_app(
 9         instance_url=mastodon_domain,
10         client=client,
11      )
12
13
14      # Get access token
15      access_token = await ActivityPub.get_auth_token(
16         instance_url=instance,
17         username=user_name,
18         password=password,
19         client=client,
20      )

Authorization URL

The sample code below shows the steps needed to generate an access token with having a user visit a URL and then input the authorization code provided on that URL to ultimately generate an access token.

 1from minimal_activitypub.client_2_server import ActivityPub
 2from httpx import AsyncClient
 3
 4async def get_access_token(mastodon_domain):
 5
 6   async with AsyncClient(http2=True) as client:
 7      # Create app
 8      client_id, client_secret = await ActivityPub.create_app(
 9         instance_url=mastodon_domain,
10         client=client,
11      )
12
13      # Get Authorization Code / URL
14      authorization_request_url = (
15         await ActivityPub.generate_authorization_url(
16             instance_url=mastodon_domain,
17             client_id=client_id,
18             user_agent=USER_AGENT,
19         )
20      )
21      print(
22         f"Please go to the following URL and follow the instructions:\n"
23         f"{authorization_request_url}"
24      )
25      authorization_code = input("[...] Please enter the authorization code:")
26
27      # Validate authorization code and get access token
28      access_token = await ActivityPub.validate_authorization_code(
29         client=client,
30         instance_url=mastodon_domain,
31         authorization_code=authorization_code,
32         client_id=client_id,
33         client_secret=client_secret,
34      )
35
36      # Verify access token works
37      mastodon = ActivityPub(
38         instance=mastodon_domain,
39         access_token=access_token,
40         client=client,
41      )
42      await mastodon.determine_instance_type()
43      user_info = await mastodon.verify_credentials()

Method Signatures

Following are the method signatures used in the above examples.

class minimal_activitypub.client_2_server.ActivityPub

Simplifies interacting with an ActivityPub server / instance.

This is a minimal implementation only implementing methods needed for the function of MastodonAmnesia

__init__(instance, client, access_token=None)

Initialise ActivityPub instance with reasonable default values.

Parameters:

  • instance (str) – domain name or url to instance to connect to

  • client (AsyncClient) – httpx AsyncClient to use for communicating with instance

  • access_token (str | None) – authentication token

  • self (ActivityPubClass)

Return type:

None

__new__(**kwargs)
async static create_app(instance_url, client, user_agent='Minimal-ActivityPub_v1.3.0_Python_3.13.0', client_website='https://pypi.org/project/minimal-activitypub/')

Create an app.

Parameters:

  • instance_url (str) – The URL of the Mastodon instance you want to connect to

  • client (AsyncClient) – httpx.AsyncClient

  • user_agent (str) – User agent identifier to use. Defaults to minimal_activitypub related one.

  • client_website (str) – Link to site for user_agent. Defaults to link to minimal_activitypub on Pypi.org

Returns:

tuple(client_id, client_secret)

Return type:

Tuple[str, str]

async determine_instance_type()

Check if the instance is a Pleroma instance or not.

Parameters:

self (ActivityPubClass)

Return type:

None

async static generate_authorization_url(instance_url, client_id, user_agent='Minimal-ActivityPub_v1.3.0_Python_3.13.0')

Create URL to get access token interactively from website.

Parameters:

  • instance_url (str) – The URL of the Mastodon instance you want to connect to

  • client_id (str) – Client id of app as generated by create_app method

  • user_agent (str) – User agent identifier to use. Defaults to minimal_activitypub related one.

Returns:

String containing URL to visit to get access token interactively from instance.

Return type:

str

async static get_auth_token(instance_url, username, password, client, user_agent='Minimal-ActivityPub_v1.3.0_Python_3.13.0', client_website='https://pypi.org/project/minimal-activitypub/')

Create an app and use it to get an access token.

Parameters:

  • instance_url (str) – The URL of the Mastodon instance you want to connect to

  • username (str) – The username of the account you want to get an auth_token for

  • password (str) – The password of the account you want to get an auth_token for

  • client (AsyncClient) – httpx.AsyncClient

  • user_agent (str) – User agent identifier to use. Defaults to minimal_activitypub related one.

  • client_website (str) – Link to site for user_agent. Defaults to link to minimal_activitypub on Pypi.org

Returns:

The access token is being returned.

Return type:

str

async static validate_authorization_code(client, instance_url, authorization_code, client_id, client_secret)

Validate an authorization code and get access token needed for API access.

Parameters:

  • client (AsyncClient) – httpx.AsyncClient

  • instance_url (str) – The URL of the Mastodon instance you want to connect to

  • authorization_code (str) – authorization code

  • client_id (str) – client id as returned by create_app method

  • client_secret (str) – client secret as returned by create_app method

Returns:

access token

Return type:

str

async verify_credentials()

Verify the credentials of the user.

Returns:

The response is a JSON object containing the account’s information.

Parameters:

self (ActivityPubClass)

Return type:

Any