# Authentication

To access the resources in the Moneybird API, you first need to
authenticate the user. This can be done through the
[OAuth2](http://oauth.net/2/) 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](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](http://tools.ietf.org/html/rfc6749#section-3.3). The following
scopes are available in Moneybird:

- `sales_invoices`
- `documents`
- `estimates`
- `bank`
- `time_entries`
- `settings`

For a personal API token, you can use the checkboxes to select the
scopes you need. When you use an external OAuth application, you need to
provide the scopes as a parameter in the authorization request.

Please note that either the `sales_invoices`, `documents`, `estimates`,
`bank` or `settings` scope is required to access contacts within the
Moneybird API. Having access to only `time_entries` will not allow you
to access contacts.

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](http://oauth.net/2/):

1.  In your application, obtain a request token and authorize URL using
    a [Authorization
    Request](https://tools.ietf.org/html/rfc6749#section-4.1.1). The
    `client_id` and `redirect_uri` parameters *must exactly* match those
    from the application you created in [Registration of your
    application](#registration-of-your-application):
    ```bash
    curl -vv \
        'https://moneybird.com/oauth/authorize?client_id=9a833de2d13b07dfdfb50a8124b148d8&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code'
    ```
    If you want to use specific scopes, you can add the `scope` parameter:
    ```bash
    curl -vv \
        'https://moneybird.com/oauth/authorize?client_id=9a833de2d13b07dfdfb50a8124b148d8&redirect_uri=urn:ietf:wg:oauth:2.0:oob&response_type=code&scope=extimates%20bank'
    ```

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:
    ![Create a new OAuth authorization](https://app-media-cdn.moneybird.com/style_checker/o_auth_authorizations/new_light_desktop_public_image.png)

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.
    ```bash
    1192e141cfd1839e1d477ac0f91268deec523fae5d14748547a8a22fc3a5b39b
    ```

4.  With the tokens provided in the request, you can exchange your
    request token for an access token with an [Access Token
    Request](https://tools.ietf.org/html/rfc6749#section-4.1.3):
    ```bash
    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
    ```
    ```json
    {
      "access_token":"b3f3bcf941029c00f602863492e188a64397c0f38be6a178e32721b6e3999621",
      "token_type":"bearer",
      "refresh_token":"9ef39031f3b31fe2af68a7390ecaf370f9321ddb74c5b8fdff91fd3aaf17dcce",
      "scope":"sales_invoices",
      "created_at":1471524338
    }
    ```

5.  The [response](https://tools.ietf.org/html/rfc6749#section-4.2.2)
    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.

6.  To refresh an access token with the refresh token, call the token
    url:
    ```bash
    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](http://oauth.net/2/) 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:

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