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.
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 together with the redirect URL you entered to identify your application when requesting access for users.
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:
If no scope is provided, the
sales_invoices scope is used by default.
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
redirect_uriparameters must exactly match those from the application you created in Registration of your application:
The response of the HTTP request contains a
Locationheader 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 URIyou provided in the first step. If you use the
urn:ietf:wg:oauth:2.0:oobredirect 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.
- With the tokens provided in the request, you can exchange your request token for an access token with an Access Token Request:
The response contains an
Access tokenwhich you can use to connect with the API. The
Refresh tokencan be used to retrieve a new access token in case the access token can expire. In that case, an
expires_inis 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:
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.