Dualog User API Documentation

Overview

The Dualog User API facilitates the extraction of user data from the Dualog system using the SCIM schema. This guide covers authentication steps and request procedures for accessing user data.

Authentication

To authenticate, obtain an OAuth 2.0 token via client credentials and use this token to access the API endpoints.

Obtaining a Client ID and Secret

To interact with the Dualog User API, you will need a client ID and client secret.

Creation Process

To create an API Client, navigate to the Organization page within the Dualog portal. At the bottom of this page, you will find the option to create a new API Client.

User vs Organisation

Client IDs and secrets can be generated either for individual users or for organizations. When you create an identity client for a user, the access scope includes all organizations the user has access to. If created for an organization, the access scope is limited to only that organization. This access is re-evaluated with each API request, ensuring current permissions are respected.

Client scope

During the creation process, you will select the access scopes for the client. Scopes define the API endpoints your client can access, organizing them into logical units for easier management.

For the Dualog User Sync API, you want to add crew_import in the client scope to grant access to the associated endpoints.

Scope Selection

When specifying scopes, consider the minimum necessary access your application requires to function. Limiting access to only what's needed enhances the security of your application and the Dualog system.

Once your identity client is created, you will receive a client ID and secret. Treat these credentials with the highest level of security, as they grant access to potentially sensitive information within the Dualog system.

Obtaining an OAuth 2.0 Token

1. Client Credentials Request:

   Request an OAuth 2.0 token from the Dualog Identity Server:

   POST <https://apps.dualog.com/auth/connect/token>
   

   Ensure requests use HTTPS to secure data in transit.

2. Authorization Header:

   Encode ClientId and ClientSecret as ClientId:ClientSecret in Base64 and include it in the header:

   Authorization: Basic <EncodedString>
   

3. Request Body:

   Use application/x-www-form-urlencoded content type with the following payload:

   grant_type=client_credentials&scope=crew_import
   

4. Response:

   A successful response includes an access_token, its validity (expires_in), token_type, and scope:

   {
     "access_token": "<access_token>",
     "expires_in": 86400,
     "token_type": "Bearer",
     "scope": "crew_import"
   }
   

   This indicates the token's 24-hour validity and applicable scopes. Handle this token securely.

Using the Access Token

Include the access_token in the authorization header of your API requests:

Authorization: Bearer <access_token>

SCIM Schema for User

The API returns user data in JSON format, adhering to the SCIM 2.0 ListResponse schema. Key components:

• schemas: Array containing "urn:ietf:params:scim:api:messages:2.0:ListResponse".
• totalResults: Total number of results from the query.
• startIndex: 1-based index for the first result.
• itemsPerPage: Number of results per page.
• resources: Array of user objects. Each user object includes id, userName, name (with familyName and givenName), displayName, active status, emails, and custom attributes under the urn:ietf:params:scim:schemas:extension:seafarer:2.0:User:crew schema.

Supported Fields

The Dualog User API supports a variety of fields within the SCIM schema to ensure comprehensive management of user data. Here's a breakdown of the primary fields you can expect within user objects and their significance:

Core User Fields

• id: A unique identifier for the user. This is used to reference the user across the API.
• userName: The user's login name (email address) or identifier, typically used for authentication purposes.
• name: An object that includes the user's full name details:
  • familyName: The user's last name or surname.
  • givenName: The user's first name or given name.
• displayName: The full name of the user, suitable for display purposes. It can be the same as givenName + familyName or a different preferred name.
• active: A boolean indicating whether the user's account is active or not. Useful for managing user access.
• emails: An array of objects detailing the user's email addresses. Each object can specify the email type (work, home) and whether it's the primary email.

Custom Fields

• urn:ietf:params:scim:schemas:extension:seafarer:2.0:User:crew: This is a custom extension schema to accommodate specific fields for the maritime industry, including:
  • rank: The user’s rank.
  • department: The user’s department.
  • shipName: The name of the ship the user is currently assigned to.
  • shipImo: The International Maritime Organization number for the ship, providing a unique identifier.
  • contractStartDate: A date (in yyyy-MM-dd format) when the user started working on board.
  • contractEndDate: ****A date (in yyyy-MM-dd format) when the user finishes work on board.
  • userFields: A list of custom properties set for the user. The list can be expanded in the future and includes:
    • businessUnit: The business unit the user is assigned to.

Metadata Fields

• meta: Contains metadata about the user object, such as:
  • resourceType: Type of the SCIM resource (e.g., "User").
  • created: The datetime when the user object was created.
  • lastModified: The last time the user object was updated.
  • location: The URL where the user object can be accessed.

Fetching Users

HTTP Method: GET Endpoint: https://<base-url>/api/<version>/Users

Pagination

To manage large datasets, the API supports pagination:

Requesting Paginated Data

Specify startIndex and count to paginate responses:

GET <https://<base-url>/api/<version>/Users?startIndex=1&count=10>

Paginated Response Details

The response includes totalResults, startIndex, itemsPerPage, and the actual resources. To retrieve all users, adjust startIndex in subsequent requests based on count and totalResults until all data is fetched.

Response Body:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 3,
  "startIndex": 1,
  "itemsPerPage": 3,
  "resources": [
    {
      "id": "87234",
      "userName": "example_user@acme-tankers.com",
      "displayName": "Example User",
      "active": true,
      // Additional fields omitted for brevity
    }
  ]
}

Fetching a User

HTTP Method: GET Endpoint: https://<base-url>/api/<version>/Users

{
  "id": "87234",
  "userName": "jdoe@company.com",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "displayName": "John Doe",
  "active": true,
  "emails": [
    {
      "value": "jdoe@company.com",
      "type": "work",
      "primary": true
    }
  ],
  "meta": {
    "resourceType": "User",
    "created": "2021-01-15T12:34:56Z",
    "lastModified": "2021-06-01T09:30:00Z",
    "location": "<https://example.com/api/v2/Users/87234>"
  },
  "urn:ietf:params:scim:schemas:extension:seafarer:2.0:User:crew": {
    "rank": "A/B",
    "department": "Deck",
    "shipName": "Voyager",
    "shipImo": "1234567",
    "contractStartDate": "2021-01-17",
    "contractEndDate": "2022-01-16",
    "userFields": [
    {
      "fieldName": "businessUnit",
      "fieldValue": "Company Unit"
    }
  }
}

Creating a User

HTTP Method: POST Endpoint: https://<base-url>/api/<version>/Users Content-Type: application/json

Note:

• The userName field must be an email address with a valid email domain. This email will be created for the user in Seafarer.
• The shipImo optional field must match the IMO number of the ship specified in the system.
• The contractStartDate field is only required if the shipImo field is present in the request. It must be specified in yyyy-MM-dd format and must not be older than the current date.
• The contractEndDate optional field’s ****date (in yyyy-MM-dd format) must not be before the contractStartDate field’s date. If not provided, the end date will be set one year after the start date.

Request Body:

{
  "userName": "john.doe@example.com",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "displayName": "John Doe",
  "active": true,
  "urn:ietf:params:scim:schemas:extension:seafarer:2.0:User:crew": {
    "rank": "Captain",
    "department": "Command",
    "shipImo": "7654321",
    "contractStartDate": "2023-01-01",
    "contractEndDate": "2023-12-31",
    "userFields": [
      {
        "fieldName": "businessUnit",
        "fieldValue": "Company Unit"
      }
    ]
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:seafarer:2.0:User:crew"
  ]
}

Response Body:

{
  "userName": "john.doe@example.com",
  "name": {
    "familyName": "Doe",
    "givenName": "John"
  },
  "displayName": "John Doe",
  "active": true,
  "emails": [
    {
      "value": "john.doe@example.com",
      "display": "Work Email",
      "type": "work",
      "primary": true
    }
  ],
  "urn:ietf:params:scim:schemas:extension:seafarer:2.0:User:crew": {
    "rank": "Captain",
    "department": "Command",
    "shipName": "SS Example",
    "shipImo": "7654321",
    "contractStartDate": "2023-01-01",
    "contractEndDate": "2023-12-31",
    "userFields": [
      {
        "fieldName": "businessUnit",
        "fieldValue": "Company Unit"
      }
    ]
  },
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:seafarer:2.0:User:crew"
  ]
}

Status Codes:

• 201 Created: User successfully created.
• 400 Bad Request: Invalid input data.
• 401 Unauthorized: Authentication required.
• 500 Internal Server Error: Server encountered an error.

Updating a User

HTTP Method: PUT Endpoint: https://<base-url>/api/<version>/Users/<UserId> Content-Type: application/json

Request Body: Same as the request body for creating a user. Response Body: Same as the response body for creating a user.

Status Codes:

• 200 OK: User successfully updated.
• 400 Bad Request: Invalid input data.
• 401 Unauthorized: Authentication required.
• 404 Not Found: User not found.
• 500 Internal Server Error: Server encountered an error.

Deleting a User

HTTP Method: DELETE Endpoint: https://<base-url>/api/<version>/Users/<UserId>

Status Codes:

• 204 No Content: User successfully deleted.
• 401 Unauthorized: Authentication required.
• 404 Not Found: User not found.
• 500 Internal Server Error: Server encountered an error.

Error Handling

When interacting with the Dualog User SCIM API, it's important to handle errors gracefully. The API uses standard HTTP status codes to indicate the success or failure of requests. Below are common error responses you might encounter:

• 400 Bad Request: Your request is invalid.
• 401 Unauthorized: Authentication failed. This usually means your access token is missing, invalid, or expired. Ensure you have obtained a valid token and included it in your request header.
• 403 Forbidden: You're authenticated but not authorized to perform the requested operation. Verify that your account has the necessary permissions.
• 404 Not Found: The specified resource could not be found. This could mean a wrong URL or the resource does not exist.
• 500 Internal Server Error: An unexpected error occurred on the server side. If this persists, contact Dualog support.

For each error response, the API may also provide a JSON body with more details, including a specific error message and potentially an error code. Here's an example of an error response body:

{
  "type": "<https://httpstatuses.com/400>",
  "title": "BadRequest",
  "status": 400,
  "detail": "Bad request",
  "correlationId": "91dab160-dc7d-49c0-b412-fe28720154f0"
}

Handling these errors involves checking the HTTP status code and any accompanying error message or code in the response body. Use this information to debug issues or display meaningful error messages to users. Additionally, implement retry logic for transient errors (like 500) and refresh tokens when encountering 401 errors with expired tokens.