Authentication

The Morgen Sync Service does not store Users explicitly, however it associates all resources that belong to the same person to a User ID (externally provided). The User ID must be included in a JWT, which is used to authenticate the user and authorize every request to the API.

In order to start using the Sync API on behalf of one of your users, you must have the following information:

User ID: provided by you
Morgen Client ID: provided by Morgen
Morgen Client Secret: provided by Morgen

Choose a User ID

The User ID is a unique identifier for the user that is making the request. It is used to associate all resources that belong to the same person.

You are responsible to generate a User ID and make sure it is unique for each user.
The User ID must be a string no longer than 255 characters. It must not contain any whitespace characters.

We recommend to use the same ID as the one used in your application, otherwise you will responsible to maintain a map between the Sync API User ID to your application's user ID.

Generate a Json Web Token

Each request to the API must be authenticated with a valid Json Web Token (JWT) (opens in a new tab) on behalf of the final user.

The JWT must be signed with the Client Secret of the application that is making the request. The Client Secret, together with a unique Client ID, must be provided to you by Morgen.

Here is how you can generate a JWT in NodeJS. You can use any JWT library to generate the token. Find more information about JWT in the JWT.io documentation (opens in a new tab).

const jwt = require('jsonwebtoken');
    const { MORGEN_CLIENT_ID, MORGEN_CLIENT_SECRET } = process.env;
    const payload = {
        "iss": MORGEN_CLIENT_ID,
        "sub": "user-id",
        // Optional payload fields
        "given_name": "John",
        "middle_name": "Jacob",
        "family_name": "Doe",
        "email": "john@example.com",
    };
    return jwt.sign(payload, MORGEN_CLIENT_SECRET, {
        expiresIn: 600, // 10 minutes
    });

The iss and sub fields are required. The iss field must be the Morgen Client ID of the application that is making the request. The sub field must be the User ID of the user that is making the request.

The given_name, middle_name, family_name and email fields are optional.

Make sure to set the expiresIn option to a reasonable value, e.g. 10 minutes. We recommend to generate a new token for every request, but you can also use a longer expiration time if you want to reuse the token for multiple requests.

⚠️

Your Client Secret grants access to all resources associated with your Client ID. It is paramount that you keep your Client Secret confidential and do not share it with anyone. In particular, do not include the Client Secret in your client-side code, not even as part of a bundle like an iOS or Android app.

Authenticate requests

The JWT must be passed in the Authorization header of the request, using the Bearer authentication scheme. For example:

Authorization: Bearer <JWT>

Requests with an invalid or expired JWT will be rejected with a 401 Unauthorized response. Requests trying to access resources that do not belong to the user will be rejected with a 403 Forbidden response.

Introduction Accounts