Attributes#

Getting attributes#

Method

GET https://login.company.com/blitz/api/v3/users/{subjectId}

Getting attributes of any user by his ID.

Required permissions: blitz_api_user or blitz_api_sys_users.

Returns

JSON containing user attributes. The metadata of the account is transmitted in the meta block.

Important

The instanceId attribute of metadata is needed to be able to call the following services in the future for account attribute modification and a password change.

Example

GET /blitz/api/v3/users/d2580c98‑e584‑4aad‑a591‑97a8cf45cd2a HTTP/1.1
Authorization: Bearer cNw…Nz

{
    "family_name": "Иванов",
    "sub": "d2580c98 e584 4aad a591 97a8cf45cd2a",
    "given_name": "Иван",
    "locked": false,
    "meta": {
        "instanceId": "Mzg…J1",
        "unmodifiable": [
            "sub"
        ]
    }
}

Changing an attribute#

Method

POST https://login.company.com/blitz/api/v3/users/{instanceId}

Changing user attributes by instanceId. To find out the value of instanceId, you must first use the GET method to call the service for getting the user attributes.

Required permissions: blitz_api_user_chg or blitz_api_sys_users_chg.

Request body

The values of the user attributes that are being changed.

Returns

JSON containing user attributes.

If the passed attribute values did not pass verification, the error HTTP 400 Bad Request will return and the nested JSON including:

  • the error type is input_error for cases when the request contains an incorrect or invalid value;

  • error code (error);

  • a text description of the error.

Note

Error codes and error texts can be defined specifically for various attributes and determined by the logic of validators implemented for attributes.

Example

POST /blitz/api/v3/users/Mzg…J1 HTTP/1.1
Authorization: Bearer cNw…Nz
Content-Type: application/json

{
   "family_name":"Петров"
}

{
    "family_name": "Петров",
    "given_name": "Иван",
    "locked": false,
    "sub": "5cffd68f-2cb8-4f7a-b0f3-9fa69a1fbbcd",
    "meta": {
        "instanceId": "Mzg…J1",
        "unmodifiable": [
            "sub"
        ]
    }
}

{
    "type": "input_error",
    "error": "wrong_values",
    "errors": [
        {
            "type": "input_error",
            "error": "contact_use_violation",
            "desc": "Validation mobile:79988887812 is failed.",
            "pos": "mobile"
        }
    ]
}

Changing the phone number#

Method

Special case of attribute modification.

Modes:

  • changing the phone number immediately to a confirmed one,

  • changing the phone number with confirmation..

Request body

  • phone_number is a mobile phone, in the form of a composite object with attributes:

    • value is a phone number in the format (country code)XXXXXXXXXX;

    • vrf – indicates that the phone has been confirmed – true.

Examples

Changing the number to a confirmed one
POST /blitz/api/v3/users/Mzg…J1 HTTP/1.1
Authorization: Bearer wzb…Tw
Content-Type: application/json

{
    "phone_number":
        {
            "value":"79991234567",
            "vrf":true
        }
}

{
    "given_name": "Иван",
    "family_name": "Иванов",
    "meta": {
        "instanceId": "Mzg5L…2M",
        "unmodifiable": [
            "uid"
        ]
    },
    "email": {
        "value": "aivanov+2@gmail.com",
        "vrf": true
    },
    "sub": "BIP-LIR6BO33XBBDHANE6DZPUTYVME",
    "phone_number": {
        "value": "+7(999)1234567",
        "vrf": true
    }
}
Changing the number with confirmation
POST /blitz/api/v3/users/Mzg…J1 HTTP/1.1
Content-Type: application/json
X-Forwarded-For: 200.200.100.100
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.106 Safari/537.36
Authorization: Bearer wzb…Tw

{
    "phone_number":{"value":"+79999999998","vrf":false}
}

The interim response contains an indication of the need to confirm a new phone number. The confirmation code is sent to the user at the new number.

{
    "given_name": "Иван",
    "family_name": "Иванов",
    "meta": {
        "instanceId": "Mzg5L…2M",
        "unmodifiable": [
            "sub"
        ]
    },
    "email": {
        "value": "aivanov+2@gmail.com",
        "vrf": true
    },
    "sub": "BIP-LIR6BO33XBBDHANE6DZPUTYVME",
    "notes": {
        "actions": {
            "state": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
            "exp": 300,
            "status": "code_waiting",
            "from": "+7(964)1234567",
            "attr": "mobile",
            "attempts_left": 3,
            "value": "+7(999)9999998",
            "action": "validate_mobile",
            "created": 1598446512
        }
    },
    "phone_number": {
        "value": "+7(964)1234567",
        "vrf": true
    }
}

You need to get a confirmation code for the new phone number from the user and send it to Blitz Identity Provider in the request. In the URL of this request, use the value of the actions: state parameter from response No. 1:

POST /blitz/api/v3/users/notes/validate_mobile/ch_El…yQ HTTP/1.1
Content-Type: application/json
X-Forwarded-For: 200.200.100.100
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5)…
Authorization: Bearer wzb…Tw

{
    "cmd": "code",
    "value": "123456"
}
Successful phone number change#
{
    "given_name": "Иван",
    "family_name": "Иванов",
    "meta": {
        "instanceId": "Mzg5L…2M",
        "unmodifiable": [
            "sub"
        ]
    },
    "email": {
        "value": "aivanov+2@gmail.com",
        "vrf": true
    },
    "sub": "BIP-LIR6BO33XBBDHANE6DZPUTYVME",
    "phone_number": {
        "value": "+7(999)9999998",
        "vrf": true
    }
}
Invalid code#
{
    "state": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
    "exp": 2592000,
    "from": "+7(964)1234567",
    "attr": "phone_number",
    "msg": "wrong_code",
    "attempts_left": 2,
    "created": 1649695409,
    "value": "+7(999)9999998",
    "action": "validate_mobile"
}
Exceeded the number of attempts to enter the correct code#
{
    "state": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
    "id": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
    "attr": "phone_number",
    "cause": "no_attempts_left",
    "from": "+7(964)1234567",
    "value": "+7(999)9999998",
    "action": "validate_mobile"
}
The code is expired#
{
    "state": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
    "id": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
    "attr": "phone_number",
    "cause": "code_expired",
    "from": "+7(964)1234567",
    "value": "+7(999)9999998",
    "action": "validate_mobile"
}

Changing the email address#

Method

Special case of attribute modification.

Modes:

  • changing the email immediately to a confirmed one,

  • changing email with confirmation.

Request body

  • email – email address:

    • value – email address;

    • vrf – indicates that the address has been confirmed – true;

Examples

Changing the address to a confirmed one
POST /blitz/api/v3/users/Mzg…J1 HTTP/1.1
Authorization: Bearer wzb…Tw
Content-Type: application/json

{
    "email":
        {
            "value":"mail@example.com",
            "vrf":true
        }
}

{
    "given_name": "Иван",
    "family_name": "Иванов",
    "meta": {
        "instanceId": "Mzg5LW…2M",
        "unmodifiable": [
            "sub"
        ]
    },
    "mail": {
        "value": "mail@example.com",
        "vrf": true
    },
    "sub": "BIP-LIR6BO33XBBDHANE6DZPUTYVME",
    "phone_number": {
        "value": "+7(999)1234567",
        "vrf": true
    }
}
Address change with confirmation
POST /blitz/api/v3/users/Mzg…J1 HTTP/1.1
Content-Type: application/json
X-Forwarded-For: 200.200.100.100
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.106 Safari/537.36
Authorization: Bearer wzb…Tw

{
 "email":{"value":"mail@example.com","vrf":false}
}

The interim response contains an indication of the need to confirm the new email address. The confirmation code is sent to the user at the new address.

{
    "given_name": "Иван",
    "family_name": "Иванов",
    "meta": {
        "instanceId": "Mzg5L…2M",
        "unmodifiable": [
            "sub"
        ]
    },
    "email": {
        "value": "aivanov+2@gmail.com",
        "vrf": true
    },
    "sub": "BIP-LIR6BO33XBBDHANE6DZPUTYVME",
    "notes": {
        "actions": {
            "state": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
            "exp": 86400,
            "status": "code_waiting",
            "from": "aivanov+2@gmail.com",
            "attr": "mail",
            "attempts_left": 3,
            "value": "mail@example.com",
            "action": "validate_mail",
            "created": 1598446512
        }
    },
    "phone_number": {
        "value": "+7(964)1234567",
        "vrf": true
    }
}

You need to get a confirmation code for the new email address from the user and send it to Blitz Identity Provider in the request. In the URL of this request, use the value of the actions: state parameter from response No. 1:

POST /blitz/api/v3/users/notes/validate_email/ch_El…yQ HTTP/1.1
Content-Type: application/json
X-Forwarded-For: 200.200.100.100
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5)…
Authorization: Bearer wzb…Tw

{
    "cmd": "code",
    "value": "123456"
}
Successful email address change#
{
    "given_name": "Иван",
    "family_name": "Иванов",
    "meta": {
        "instanceId": "Mzg5L…2M",
        "unmodifiable": [
            "sub"
        ]
    },
    "email": {
        "value": "mail@example.com",
        "vrf": true
    },
    "sub": "BIP-LIR6BO33XBBDHANE6DZPUTYVME",
    "phone_number": {
        "value": "+7(999)9999998",
        "vrf": true
    }
}
Invalid code#
{
    "state": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
    "exp": 2592000,
    "from": "aivanov+2@gmail.com",
    "attr": "email",
    "msg": "wrong_code",
    "attempts_left": 2,
    "created": 1649695409,
    "value": "mail@example.com",
    "action": "validate_email"
}
Exceeded the number of attempts to enter the correct code#
{
    "state": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
    "id": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
    "attr": "email",
    "cause": "no_attempts_left",
    "from": "aivanov+2@gmail.com",
    "value": "mail@example.com",
    "action": "validate_email"
}
The code is expired#
{
    "state": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
    "id": "ch_EludIw5fEDouy8wpT_GVOJ7rLxKfZUi-G3blijf34yQ",
    "attr": "email",
    "cause": "code_expired",
    "from": "aivanov+2@gmail.com",
    "value": "mail@example.com",
    "action": "validate_email"
}