Properties of a REST API method document

Purpose

This process describes adding an additional authentication method to an existing person, update authentication method and delete it.

Use GET persomperson/{id}/ authentication_method to find authentication method' id of person.

Logic

Description of the working algorithm of the API method and the interaction of services with each other add Service logic (if necessary)

Configuration parameters

...

curl -X GET \
  {:host}/prm/api/global_parameters

Dictionaries

• AUTHENTICATION_METHOD

• DOCUMENT_TYPE

Provides a list of links to dictionaries that are available in Confluence

Input

...

parameters

Request structure

See on API-specification

{
  "object": {
    "action": "DEACTIVATE",
    "authentication_method": {
      "id": "7b100a9c-daaa-490e-b88d-2a911059b055"
    }
  }
}

Headers

Request data validation

Validate Patient

• Get person_id from URL

• Validate id:

  • validate person.id UUID

    • in case error return 404

  • search person by person.id in MPI

    • in case error return 404, "Such person doesn't exist"

  • validate that person is active ( person.status = active & is_active = true)

    • in case error return 409, "Such person isn't active"

Validate request

if action = deactivate

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
  "action": "deactivate",
  "authentication_method": {
    "id": "057413fb-2c2e-4f33-b2d6-433469212744"
    }
  }
}

...

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
  "action": "insert",
  "authentication_method": {
    "type": "THIRD_PERSON",
    "value": "d12888c0-1159-4296-8f03-a592c136f673",
    "phone_number" : "+380656779678",
    "alias": "roksolana"
    }
  }
}

Search auth requests by person id

 To prevent requests duplication search in il.auth_method_requests.person_id = $.person_id and il.authentication_method_requests.status = NEW, then

...

SET   IL_DB.authentication_method_requests.status = 'CANCELED'
WHERE IL_DB.authentication_method_requests.id IN (:LIST)

Validate by actions

if action = deactivate

1. Field type must be THIRD_PERSON (where person_auth_method.id = $authentication_method.id), else return error 422 “Only THIRD_PERSON authentication method type could be deactivated"

   1. Check this auth_method is not primary & there are more than one authentication method for person:

      1. in case of error return 422, “You can't deactivate the last authentication method“

   2. Check if authentication_method_current != NA, else return error 422 “Person can't be authorized with NA authentication method"

   3. Validate that auth_method is active ( person_authentication_methods.ended_at > now())

      • in case error return 422, “Authentication method isn’t active”

if action = update

1. validate authentication_methods.id belong to this person. Search auth method of this person where  MPI.person_authentication_method.person_id = $.person.id

   1. in case error return 422, "such authentication method does not belong to this person"

2. alias is required.

3. Check if authentication_method_current != NA, else return error 422 “Person can't be authorized with NA authentication method"

if action = insert

1. if type = OTP ,

   1. phone_number is required and value shouldn’t be set. And field alias is optional.

   2. validate that person.age >global_parameters.no_self_auth_age

   3. validate that il.authentication_method_request.authentication_method.phone_number is in DB.VERIFICATION.VERIFIED_PHONES

2. if type = OFFLINE

   1. phone_numberand value shouldn’t be set . And field alias is optional.

   2. validate that person.age > global_parameters.no_self_auth_age

   3. auth_method_current != OFFLINE

      1. error - "Person already has auth method OFFLINE"

   4. auth_method_current = OTP ( if config AUTH_REQUEST_SECURITY_REDUCTION = false)

      1. error - Person cannot set OFFLINE auth method if person had OTP

3. if type = THIRD_PERSON

   1. value ,phone_number, alias are required

   2. Validate value:

      1. validate person.id is UUID

         • in case error return 422

      2. search person by person.id in MPI 

         • in case error return 404, "such person doesn't exist"

      3. search person by person.id in MPI and validate that is_active = true & status = active, else:

         • in case error return 422, "third person must be active"

      4. search third_person.age > prm.global_parameters.no_self_auth_age years:

         • in case error return 422, "Incorrect person age for such an action"

      5. validate third_person.auth_method != (MPI.person_auth_methods.ended_at <= now())

         • in case error return 422, "third person must has auth method OTP or OFFLINE"

   3. Validate phone_number with mpi.person_auth_method.phone_number where mpi.person_auth_method.person_id = auth_method_request.authentication_method.value

   4. auth_method_current != null (null is set if MPI.person_auth_methods.ended_at <= now())

   5. if config THIRD_PERSON_OFFLINE = False - validate that third_person has self method = OTP, else:

      1. error THIRD PERSON can't have OFFLINE self auth method type

   6. validate if THIRD_PERSON != person, else return error 422 Person can't add himself as THIRD_PERSON

   7. validate if person’s authentication method with type THIRD_PERSON with the same value, else return error 422 Such person id is already used in existing person's authorization methods

   8. check if person have authentication method with type THIRD_PERSON less person_with_third_person_limittimes, else return error 422, Limit of authentication methods with THIRD_PERSON type is exhausted

Processing

Set auth_method_current

Set default auth method of person on IL.auth_method_request.auth_method_current - use function in mpi, that return primary auth method.

• Validate that auth_method_current != null (null is set if MPI.person_auth_methods.ended_at <= now()) if

  • action = deactivate

  • action = update

  • action = insert and type= THIRD_PERSON and person.age>no_self_auth_method

• else error - “Person can't be authorized with NA authentication method “

Generate verification code

If auth_method_requests.auth_method_current = OTP 

Invoke Initialize OTP to generate one time password and send it where auth_method_requests.auth_method_current = OTP.

cURL example

...

...

it where auth_method_requests.auth_method_current = OTP.

cURL example

curl -X POST \
  http://localhost:4000/verifications \
  -H 'content-type: application/json' \
  -d '{
  "phone_number": "+380936235985"
}'

Generate upload URL

If auth_method_requests.auth_method_current = OFFLINE 

...

1. Generate URL's with type person.{$.person.documents.[:].type}

Response structure examples

See on API-specification

{
  "meta": {
    "code": 201,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "data": {
    "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
    "status": "NEW",
    "channel": "MIS"
  },
  "urgent": {
    "authentication_method_current": [
      {
        "type": "OTP",
        "phone_number": "+38093*****81"
      }
    ],
    "documents": [
      {
        "type": "PASSPORT",
        "url": "https://storage.ehealth.world"
      }
    ]
  }
}

Example:

{
  "meta": {
    "code": "422",
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "error": {
    "type": "unverified",
    "message": "Unverified phone number"
  }
}

HTTP status codes

Post-processing processes

Description of actions performed on data after processing

Technical modules where the method is used

List of pages describing technical modules where the method is used

...