Our API follows OAuth2.0 standard for authentication. You can currently authenticate in two ways:

• Authenticate using username and password - primarily intended to be used with staff accounts for automation and shouldn't be used by your customers
• Authenticate using authorization code - user inputs their username and password through our website and you'll only receive a token to use with the API, this way is intended to be used by your customers since the customers credentials will never reach your servers

The API is always used by a specific user and all permissions are inferred from them.

OAuth2.0 Implementation notes

Endpoint to obtain token is: /api/v2/auth/token

You can supply your client credentials as part of the POST body or as basic HTTP auth.

The access token you receive expires in a few hours after creation even when its being used, be sure to use refresh_token grant type to obtain a new one if that happens.

OAuth2.0 Flows

Authorization Code Flow

This flow allows your customers to sign in through our website and give you a token to be used to communicate with our API. This way their credentials never leave our service.

To obtain a token using this flow you need to:

1. Add Redirect URI to your OAuth client in the API dashboard - the URI should point to your webserver that'll receive the authorization code and generate a token from it
2. Redirect user to /api/v2/auth/authorize - they'll be shown a normal Momence login screen with your specific customizations
3. User logs in through Momence login screen
4. User gets redirected back to your app with code parameter
5. Make a POST request to /api/v2/auth/token with authorization_code grant type and code parameter to obtain regular token which can then be used to authorize requests

See https://oauth.net/2/grant-types/authorization-code/ for more info.

Password Flow

Password flow allows you to login as a specific user if you know their username and password. It should only be used for your own staff accounts as it's unsafe to work with your clients user password.

To obtain a token using this flow you need to make a POST request to /api/v2/auth/token with password grant type and proper credentials.

See https://oauth.net/2/grant-types/password/ for more info.

Refresh Token Flow

Refresh token flow allows you to obtain a new access token using a refresh token.

To obtain a token using this flow you need to make a POST request to /api/v2/auth/token with refresh_token grant type and refresh_token parameter.

You'll receive a new access and refresh token.