Registration invitations (invites)

Overview

Manages user registration invitations.

Two-step algorithm:

  • 1. POST request from an authorized domain administrator to send an email with a registration invitation link.

    • 1.1. Check for the 'userid' field in the JSON request body. The domain is the same one the administrator is authorized in.

    • 1.2. Create the system/Invites entity with a 3-day lifetime limit.

    • 1.3. Send an email to the user with a link containing the UUID of the registration request. The link leads to the system web application /app-root, but it contains an identifier that can be used to call the API directly with a PATCH request.

  • 2. PATCH request to change the password.

    • 2.1. Check for the 'pwd' field and optionally 'login' and 'name' in the JSON request body.

    • 2.2. Verify the invitation validity based on the identifier passed in the URL.

    • 2.3. Send a request to change the password and optionally login and name to MDC and check the password complexity policy.

    • 2.4. On success, delete the system/Invites entity.

Servicing is performed by the mware, email, and ws microservices.

For successful email sending, configure the mail server profile, the mail server account, and set its 'isSystem' flag.

Requests

HTTP verb Endpoint Description

POST

/rest/v1/iam/invites

Sending an invitation

PATCH

/rest/v1/iam/invites/<id>

Replacing a forgotten password (without authorization)


Sending an invitation

Performed by the domain administrator.

An invitation may be sent no more than once every 2 minutes for the same email address and from the same IP address.

Request

Example request
POST /rest/v1/iam/invites HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "userid": "12341234-1234-1234-1234-123412341234"
}

Response

Example successful response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "error_code": 0,
  "result": true,
  "result_msg": "Email was ordered"
}
Example failed response
HTTP/1.1 412 Precondition failed
Content-Type: application/json; charset=utf-8

{
  "error_code": 1413,
  "error_message": "User not found."
}

Replacing a forgotten password (without authorization)

Step 2/2 of the two-step forgotten password recovery algorithm.

The login and name fields are optional and are not changed by default.

Request

Example request
PATCH /rest/v1/iam/invites/602c559c-0183-a834-ee7d-7cd30a921f58 HTTP/1.1
Content-Type: application/json; charset=utf-8

{
  "pwd": "ew!hIb3V",
  "login": "mylogin",
  "name": "My Name"
}

Response

Example successful response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "error_code": 0,
  "result": true,
  "result_msg": "Now login with new password",
  "user": {
    "domain": "pbx.incoplax.com",
    "login": "mylogin"
  }
}
Example failed response
HTTP/1.1 412 Precondition failed
Content-Type: application/json; charset=utf-8

{
  "error_code": 1501,
  "error_message": "pwd contains invalid symbols. Expected: A-Za-z0-9_-.~!",
  "error_details":{
    "field": "pwd"
  }
}

Error codes

Possible message types (the 'error_details.msg_code' field): 100xx, 101xx, 102xx, 151xx.