Getting Started

Authentication

Authentication to REST API is based on the Oauth2 standard. Using of all API functions requires a valid Oauth2 bearer token. Expiry is set on server side and the mechanism to handle the expiry of the token is suggested to be handled gracefully on the client side.

The endpoint for aquiring the token is POST /oauth2/token. This endpoint provides authentication to all of the Maventa REST APIs.

• When starting a session, request for an authentication token via POST /oauth2/token
• Store the token locally, and set it to expire in given time before the server side value returned in response as seconds in expires_in field
  • Use the token until the stored validity time is reached, and then request a new token
  • When storing the token note that it is just a signed JSON so the length is not fixed. Be prepare that the number of characters in token may change
• Build in graceful authentication error handling
  • Prepare to handle possible token expiry errors even though using the client side expiry time, by requesting a new token
  • Handle token access and token unauthorized/expired scenarios differently (if token granted per client id&secret does not grant access to given resource, asking for a new token will not help)

Authenticate as a company

Authenticating requires a user_api_key and company_id. To create an account in testing, registrations can be done in Maventa Web UI.

Also you need a vendor_api_key. When you have registered a company account in testing, contact your integration contact point or Maventa support to convert your account into a partner account and create a vendor_api_key for you.

Call the POST /oauth2/token method with company credentials:

• client_id = Company UUID (log in to your Maventa account to get it)
• client_secret = User API key (log in to your Maventa account to get it)
• vendor_api_key

Notes:

• Currently only one level of user rights, admin, is supported. So all authenticated users will be granted with admin rights
• For Maventa company authentication, the scope does not need to be provided

Authenticate as an operator

Call the POST /oauth2/token method with operator credentials:

• client_id = operator_id
• client_secret = operator_secret

Error handling

The client should always handle any server/connection issues gracefully. Do not lock up or throw exceptions directly at your users. There can be both scheduled and unscheduled breaks in the service which should be handled on the client side, for example with messages like “Service unavailable, please try again later”.

Endpoints

Maventa REST API is technically split into multiple URLs:

But you should not care about that too much, the split is only technical. The authentication between all the methods under all these URL endpoint is the same.