Authentication

To access the resources in the Moneybird API, you first need to authenticate the user. This can be done through the OAuth2 protocol, which allows limited access to a HTTP service with secured resources. Alternatively, you can create a personal API token that simplifies the setup, at a cost of security.

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.

When registering, you get the option to either create a personal API token that you can use as a Bearer token or registering an external OAuth application.

After registering, you will either receive a Bearer token when registering a personal API token, or you will receive a Client ID and Client Secret for the external OAuth application. When using a personal API token, ensure that you store this token securely. It is similar to a password and gives access to your entire company account.

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
time_entries
settings

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

Authentication using Oauth

In order to access the API on behalf 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:

In your application, obtain a request token and authorize URL using a Authorization Request. The client_id and redirect_uri parameters must exactly match those from the application you created in Registration of your application:
```
curl -vv \
  'https://moneybird.com/oauth/authorize?client_id=9a833de2d13b07dfdfb50a8124b148d8&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code'
    
```
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:
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
    
```

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
}

The response contains an Access token which you can use to connect with the API. The Refresh token can be used to retrieve 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.

As of now, this token does not expire, but we might change this in the future. Therefore it is advised to keep this in mind and prepare your application accordingly.

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.

Accessing resources using the access token

To access a resource in Moneybird, you will need an access token. You can retrieve the access token through the above OAuth process. Alternatively, you can use an API token for personal usage when your application does not support OAuth.

Add the access token in the Authorization header of every request to the API:

curl -XGET -H "Content-Type: application/json" -H "Authorization: Bearer 84ec207ad0154a508f798e615a998ac1fd752926d00f955fb1df3e144cba44ab" https://moneybird.com/api/v2/107693607045039116/contacts.json