Authentication

Two authentication methods are supported:

Token authentication

Token authentication is the simplest form of authentication. In the MoneyBird application a token can be generated, which you can pass to your TokenAuthentication instance.

Token authentication is useful when your application only accesses a single MoneyBird administration. Token authentication is not recommended when you want to access multiple administrations, especially not when you access administrations belonging to users of your application. Please use OAuth authentication instead.

from moneybird import TokenAuthentication

auth = TokenAuthentication('my_moneybird_token')

Warning

Never include your token in your source code since this token can be (mis)used to access your MoneyBird account!

I recommend to pass your token to your application using a local configuration file, or even better, an environment variable.

OAuth authentication

OAuth authentication can be used when your application accesses multiple administrations. Using OAuth, the user authorizes your application using a secure process. OAuth requires interaction with the user to work.

This documentation assumes that the reader has a sufficient knowledge of the OAuth technology and the processes related to it.

Details about the MoneyBird OAuth implementation can be found here.

Prerequisites

For OAuth authentication your application has to be registered in MoneyBird. MoneyBird will provide you with a client id and a client secret. Both these values are required by the OAuth authentication implementation.

Warning

Never include your client id and/or client secret in your source code!

The OAuth authentication can be set up as follows:

from moneybird import OAuthAuthentication

auth = OAuthAuthentication(
    redirect_url='https://yoursite.example.com/oauth/callback/',
    client_id='your_client_id',
    client_secret='your_client_secret',
)

Requesting authorization

Before you can do any API calls, an access token needs to be obtained. This can be done by redirecting the user to the authorize url. This url can be obtained using OAuthAuthentication.authorize_url().

The response from MoneyBird can be processed and exchanged for an access token using OAuthAuthentication.obtain_token().

Authenticating a user

When an access token has been obtained this token can be used to perform API calls. The OAuthAuthentication instance can be (re)used, or the obtained token can be used with a new TokenAuthentication instance.

from moneybird import MoneyBird, OAuthAuthentication

auth = OAuthAuthentication(
    redirect_url='https://yoursite.example.com/oauth/callback/',
    client_id='your_client_id',
    client_secret='your_client_secret',
)
auth.obtain_token('https://yoursite.example.com/oauth/callback/?code=any&state=random_string', 'random_string')

moneybird = MoneyBird(auth)

from moneybird import MoneyBird, OAuthAuthentication

auth = OAuthAuthentication(
    redirect_url='https://yoursite.example.com/oauth/callback/',
    client_id='your_client_id',
    client_secret='your_client_secret',
)
access_token = auth.obtain_token('https://yoursite.example.com/oauth/callback/?code=any&state=random_string', 'random_string')

moneybird = MoneyBird(TokenAuthentication(access_token))

The access token can be stored for later use. At the moment of writing MoneyBird access tokens do not expire. However, a user might remove the authorization for the token, making the API inaccessible using the token.

For convenience, OAuthAuthentication.__init__() also acceps an auth_token parameter. This enables you to always use an OAuthAuthentication instance regardless of whether you already have a token or not.

Internal API

class moneybird.authentication.Authentication[source]

Bases: object

Base class for authentication implementations.

get_session() → requests.sessions.Session[source]

Creates a new session with the authentication settings applied.

Returns:The new session
is_ready() → bool[source]

Checks whether authentication can be performed. A negative result means that it is certain that a request will not authenticate.

Returns:Whether the authentication is ready to be used
class moneybird.authentication.OAuthAuthentication(redirect_url: str, client_id: str, client_secret: str, auth_token: str = '')[source]

Bases: moneybird.authentication.Authentication

OAuth authentication for the MoneyBird API.

This is a wrapper around TokenAuthentication since token authentication is used after the OAuth process has been performed. This authentication method cannot be used directly, some work is required since the user has to perform a number of actions before a token can be obtained.

Parameters:
  • redirect_url – The URL to redirect to after successful authorization
  • client_id – The OAuth client id obtained from MoneyBird
  • client_secret – The OAuth client secret obtained from MoneyBird
  • auth_token – The optional token from an earlier authorization
exception OAuthError(error_code: str, description: str = None)[source]

Bases: Exception

Exception for OAuth protocol errors.

OAuthAuthentication.authorize_url(scope: list, state: str = None) → tuple[source]

Returns the URL to which the user can be redirected to authorize your application to access his/her account and the state which can be used for CSRF protection as a tuple.

Example:
>>> auth = OAuthAuthentication('https://example.com/oauth/moneybird/', 'your_id', 'your_secret')
>>> auth.authorize_url()
('https://moneybird.com/oauth/authorize?client_id=your_id&redirect_uri=https%3A%2F%2Fexample.com%2Flogin%2F
moneybird&state=random_string', 'random_string')
Parameters:
  • scope – The requested scope
  • state – Optional state, when omitted a random value is generated
Returns:

2-tuple containing the URL to redirect the user to and the randomly generated state
OAuthAuthentication.obtain_token(redirect_url: str, state: str) → str[source]

Exchange the code obtained using authorize_url for an authorization token.

Example:
>>> auth = OAuthAuthentication('https://example.com/oauth/moneybird/', 'your_id', 'your_secret')
>>> auth.obtain_token('https://example.com/oauth/moneybird/?code=any&state=random_string', 'random_string')
'token_for_auth'
>>> auth.is_ready()
True
Parameters:
  • redirect_url – The full URL the user was redirected to
  • state – The state used in the authorize url
Returns:

The authorization token
class moneybird.authentication.TokenAuthentication(auth_token: str = '')[source]

Bases: moneybird.authentication.Authentication

Token authentication for the MoneyBird API.

Parameters:auth_token – The authentication token to use.
set_token(auth_token: str)[source]

Sets the authentication token.

Parameters:auth_token – The authentication token to use.