Customer API – Getting Started

INTRODUCTION

The Customer API can be used to programmatically retrieve data from Dualog services. This will make it possible to integrate data from Dualog services with data from internal or other external systems.

AUTHENTICATION AND AUTHORIZATION

Requests to the Customer API require authentication.

Your applications request will be identified by an OAuth 2.0 token. The token will contain information about the application using the API in addition to which organization requested endpoints will allow access to.

OAuth 2.0 is the only way to authorize request. Dualog does not support any other authorization methods.

The OAuth 2.0 token can be obtained by doing requests to the Dualog Identity Server using a Client Id and a Client Secret.

Client Id and Client Secret can be created for a specific user or a specific organization. If an identity client is created for a user, access will be given to all organizations a user has access to. This will be evaluated every time a request is posted to the API.

Creation of identity clients can be done in the portal at the bottom of the Organization page.

In the process of creating an identity client you will also be prompted for which scopes the client will have access to. Scope is used to group collection of endpoints in logical units. The organization_read scope is the basic scope that identifies ships. An identity client should always be given access to this scope.

The other scopes are matched with read and write access to the Dualog services.

DOCUMENTATION OF ENDPOINTS

Documentation of endpoints are based on the Swagger framework. There is one Swagger documentation page available per service.

Links to Swagger documentation of endpoints is available from the page where identity clients are created. Overview of endpoints will appear in the following format

The following list of Swagger documentation pages are available

• Generic organization endpoints - scope organization_read.
  https://apps.dualog.com/api/dp-customer-organization-public-api/index.html
• Drive endpoints – scope drive_read.
  https://apps.dualog.com/api/dr-customer-public-api/index.html

TESTING ENDPOINTS

Endpoints can also be tested on the Swagger documentation page.

You can use the Authorize button to provide the client id and secret obtained from the creation of identity client. Scroll to the oAuth2ClientCredentials section and fill in.

Make sure you select the scope in the authentication process

When pressing Authorize the page obtains a token from the identity server. When the token is successfully acquired endpoints are ready to be used.

There is one Swagger based documentation page per service. All endpoints documented on the page belongs to the service. Make sure you select the scope in the authentication process.

After getting positive response on the authorize process the authorization window can be closed. Swagger has now a valid token. The token is valid for 24 hours.

All endpoints are documented with request type, input and output. The “Try it out”-button on each endpoint will force you to add correct input parameters and the result set is provided according to the documented output.

PROGRAMMATICALLY ACQUIRE TOKEN

When a client application is acquiring a token, a request must be sent to the Dualog provided identity server. The url to the client credentials endpoint is

https://apps.dualog.com/auth/connect/token

The client id and the client secret must be concatenated in the following format

<ClientId>:<ClientSecret>

and then base 64 encoded.

The encoded string should be put in the request header like this

authorization: Basic <EncodedString>

In the payload the following should be added

grant_type=client_credentials&scope=<space separated list of scopes>

If the request is successfully the endpoint will return 200 status code with the following object:

{"access_token":"<access_token>","expires_in":86400,"token_type":"Bearer","scope":"<list of scopes>"}

The returned object indicates that the given access token will be valid for 86400 seconds (24 hours) and will be valid for endpoints belonging to on of the scopes in the list of scopes.

The returned access token should be used in the authorization part of the request header when accessing the specific endpoints.

authorization: Bearer <access_token>

Urls and request objects to endpoints can be found in the Swagger documentation pages.