To access the Moneybird API, you need to authenticate the user. Authentication is done via the OAuth2 protocol, which allows limited access to a HTTP service with secured resources.

Registration of your application

Before you can use OAuth2 in our API, you need to register your application with Moneybird. Registration allows us to see which application is authenticating and who is the owner of the application. Registration is a one-time event for the developer and can be done by logging in to your Moneybird account and visit the page https://moneybird.com/user/applications/new.

After registration you will receive a Client ID and Client Secret. You will use these tokens to identify your application when requesting access for users.

Scopes

Your application can be limited to receive access to limited parts of the administration. This is done by using scopes. The following scopes are available in Moneybird:

  • sales_invoices
  • documents
  • estimates
  • bank
  • settings

If no scope is provided, the sales_invoices scope is used by default.

Authentication

In order to access the API in behave of a user, you need to get an access token. This token will give you access to the resource belonging to the user in the given scope. During the authentication of your user, Moneybird creates a special API user with access to the administration. All actions performed by your application, will be named based on the application you registered.

Authenticating a user consists of the following steps, as prescribed by the OAuth 2.0 protocol:

  1. In your application, obtain a request token and authorize url using a Authorization Request:
    curl -vv \
      'https://moneybird.com/oauth/authorize?client_id=9a833de2d13b07dfdfb50a8124b148d8&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code'
  2. The response of the HTTP request contains a Location header and HTML content pointing towards an authorize url. Redirect your user to this url. Moneybird present the user with a login screen, checks all credentials (user should be owner of the administration) and presents the user with an authorization screen:
  3. When the user authorizes your application, Moneybird redirects the user to the redirect URI you provided in the first step. If you use the urn:ietf:wg:oauth:2.0:oob redirect URI to indicate that the redirect URI is Out-of-Band, the user will not be redirected. Instead the code is displayed in the webbrowser.
    1192e141cfd1839e1d477ac0f91268deec523fae5d14748547a8a22fc3a5b39b
  4. With the tokens provided in the request, you can exchange your request token for an access token with an Access Token Request:
    curl -vv \
      -X POST \
      -d "client_id=9a833de2d13b07dfdfb50a8124b148d8&client_secret=b376c8fbed732a5d1495a510a2f7d2738cdd4986516f1d34dd5cc00de4dcfe11&code=1192e141cfd1839e1d477ac0f91268deec523fae5d14748547a8a22fc3a5b39b&redirect_uri=urn:ietf:wg:oauth:2.0:oob&grant_type=authorization_code" \
      https://moneybird.com/oauth/token
    {
      "access_token":"b3f3bcf941029c00f602863492e188a64397c0f38be6a178e32721b6e3999621",
      "token_type":"bearer",
      "refresh_token":"9ef39031f3b31fe2af68a7390ecaf370f9321ddb74c5b8fdff91fd3aaf17dcce",
      "scope":"sales_invoices",
      "created_at":1471524338
    }
  5. The reponse contains an Access token which you can use to connect with the API. The Refresh token can be used to retreive a new access token in case the access token can expire. In that case, an expires_in is given. Both the access token and the refresh token should be persisted to be used for future requests.
  6. To refresh an access token with the refresh token, call the token url:
    curl -vv \
      -X POST \
      -d "client_id=9a833de2d13b07dfdfb50a8124b148d8&client_secret=b376c8fbed732a5d1495a510a2f7d2738cdd4986516f1d34dd5cc00de4dcfe11&grant_type=refresh_token&refresh_token=9ef39031f3b31fe2af68a7390ecaf370f9321ddb74c5b8fdff91fd3aaf17dcce" \
      https://moneybird.com/oauth/token
There are plenty of OAuth 2.0 client libraries that can be used to make the CURL commands in the above example easier. The OAuth 2.0 website has a list with client libraries and documentation.