Registration#

Method

PUT https://login.company.com/blitz/reg/api/v3/users

Registration of a user account.

Required permissions: blitz_api_sys_users_reg.

Headers

To send an e-mail in English, specify the Accept-Language: en header (available only in v3).

Request body

user.attrs block

Attributes of the account being registered:

first_name is a surname;
name is the name;
middle_name is a middle name;
phone_number is a mobile phone number in the form of a composite object with attributes:
- value is a phone number in the format (country code)XXXXXXXXXX;
- verified – indicates that the phone has been verified – true or false;
email – an email address in the form of a composite object with attributes:
- value – email address;
- verified – indicates that the address has been verified – true or false;

user.credentials block

Optional block.

password is the password for the user account being created (must match the configured password policy).

actions block

Optional block.

Actions performed after account registration:

bindDynClient - after registering an account, it is necessary to associate with it the previously released free dynamic client_id of the mobile application instance.

It is used when registering a user from a mobile application.

Parameters:
- type is the name of the action. The value bindDynClient must be passed;
- client_id is a value containing a dynamic client_id.
```
"actions": [
    {
        "type": "bindDynClient",
        "client_id": "dyn~test_app~af…59"
    }
]
```

Examples

Registration with a confirmed email and phone number

Request

PUT /blitz/reg/api/v3/users HTTP/1.1
Authorization: Bearer cNw…Nz
Content-Type: application/json

{
    "user": {
        "attrs": {
            "sub": "BIP-9TZYWXQ",
            "family_name": "Иванов",
            "given_name": "Иван",
            "middle_name": "Иванович",
            "email": {
                "value": "ivan.ivanov@example.com",
                "verified": true
            },
            "phone_number": {
                "value": "79991234567",
                "verified": true
            }
        },
        "credentials": {
            "password": "Qwerty_123"
        }
    }
}

Response

{
    "instanceId": "Yml…Yw",
    "subject": "BIP-9TZYWXQ",
    "context": "M0F…pQ",
    "cookies": [
        {
            "name": "css",
            "value": "cp0…1o"
        }
    ],
    "instructions": []
}

Errors

The password does not comply with the password policy#

{
    "errors": [
        {
            "errMsg": "Пароль не соответствует парольным политикам: длина менее 8 символов, не содержит цифру, прописную букву, специальный символ.",
            "field": "password"
        }
    ],
    "context": ""
}

The uniqueness of the fields is violated#

{
    "errors": [
        {
            "errMsg": "Пользователь с таким значением уже зарегистрирован. Для дальнейшей регистрации введите другое значение",
            "field": "phone_number"
        },
        {
            "errMsg": "Пользователь с таким значением уже зарегистрирован. Для дальнейшей регистрации введите другое значение",
            "field": "email"
        },
        {
            "errMsg": "Пользователь с таким значением уже зарегистрирован. Для дальнейшей регистрации введите другое значение",
            "field": "sub"
        }
    ],
    "context": ""
}

Registration with an unconfirmed email and phone number

Request

PUT /blitz/reg/api/v3/users HTTP/1.1
Authorization: Bearer cNw…Nz
Content-Type: application/json

{
    "user": {
        "attrs": {
            "sub": "BIP-1TZYWXQ",
            "family_name": "Иванов",
            "given_name": "Иван",
            "middle_name": "Иванович",
            "email": {
                "value": "ivan.ivanov@example.com",
                "verified": false
            },
            "phone_number": {
                "value": "79991234567",
                "verified": false
            }
        },
        "credentials": {
            "password": "Qwerty_123"
        }
    }
}

Response No.1

If registration is caused by the transmission of an unconfirmed phone and/or email, the service will send the user a verification SMS with a confirmation code and/or email with a confirmation code and return the service attributes instructions and context.

The response is when the user needs to enter verification codes:

{
    "context": "NIi…qQ",
    "instructions": [
        {
            "mobile": "+79991234567",
            "exp": 1690444604,
            "attemts": 3,
            "name": "mbl-enter-code"
        },
        {
            "email": "ivan.ivanov@example.com",
            "exp": 1690644970,
            "attemts": 3,
            "name": "eml-enter-code"
        }
    ]
}

The registration service can be configured so that the user is registered immediately, and contacts are registered in the account after confirmation, in this case, the registration service will return the parameters of the registered account (instanceId, subject, cookies), as well as instructions for optional confirmation of contacts in the account:

{
    "instanceId": "Yml…Yw",
    "subject": "BIP-1TZYWXQ",
    "context": "NIi…qQ",
    "cookies": [
        {
            "name": "css",
            "value": "t8_…84"
        }
    ],
    "instructions": [
        {
            "mobile": "+79991234567",
            "exp": 1690444604,
            "attemts": 3,
            "name": "mbl-enter-code"
        },
        {
            "email": "ivan.ivanov@example.com",
            "exp": 1690644970,
            "attemts": 3,
            "name": "eml-enter-code"
        }
    ]
}

Confirmation codes

When receiving the instructions eml-enter-code and/or mbl-enter-code in response No. 1, you need to ask the user to enter the confirmation code sent to email and mobile phone. After entering each code, call the service to confirm the contact specified during registration by passing the value from the context parameter to the request URL, and the confirmation code entered by the user in the request body:

Email confirmation request#

POST /blitz/reg/api/v3/users/YNx9…Dw HTTP/1.1
Authorization: Bearer cNw…Nz
Content-Type: application/json

{
    "email_code":"269302"
}

The response if the wrong code is entered from the email#

{
    "instructions": [
        {
            "email":"mail123@example.com",
            "exp":1655283696,
            "attemts":2,
            "name":"eml-try-again"},
        {
            "mobile":"79988984169",
            "exp":1655280756,
            "attemts":3,
            "name":"mbl-try-again"
        }
    ],
    "context":"kE6r…7g"
}

Response if the expiration date has expired or the number of attempts has been exceeded (there will be a general error eml-expired)#

{
    "instructions": [
        {
            "email":"mail123@example.com",
            "name":"eml-expired"
        },
        {
            "mobile":"79988984169",
            "exp":1655280756,
            "attemts":3,"name":"mbl-try-again"
        }
    ],
    "context":"kE6r…7g"
}

Request to initiate the re-sending of the code by email (specify any code as the parameter value)#

POST /blitz/reg/api/v3/users/YNx9…Dw HTTP/1.1
Authorization: Bearer cNw…Nz
Content-Type: application/json

{
    "email_code_resend":"123456"
}

If the email has been successfully confirmed, and it remains to confirm the phone, then the instructions about confirming the email will disappear in the service’s response, and only the instructions about the phone will remain:

Response if the email is confirmed, but you need to confirm the phone number#

{
    "instructions": [
        {
            "mobile":"79988984169",
            "exp":1655280756,
            "attemts":3,
            "name":"mbl-try-again"
        }
    ],
    "context":"kE6r…7g"
}

Phone number confirmation request#

POST /blitz/reg/api/v3/users/YNx9…Dw HTTP/1.1
Authorization: Bearer cNw…Nz
Content-Type: application/json

{
    "sms_code":"953568"
}

Response if the wrong phone verification code is entered#

{
    "instructions": [
        {
            "email":"mail123@example.com",
            "exp":1655283696,
            "attemts":2,
            "name":"eml-try-again"},
        {
            "mobile":"79988984169",
            "exp":1655280756,
            "attemts":3,
            "name":"mbl-try-again"
        }
    ],
    "context":"kE6r…7g"
}

Response if the expiration date has expired#

{
    "instructions": [
        {
            "mobile":"79988984169",
            "name":"mbl-expired"
        }
    ],
    "context":"kE6r…7g"
}

Response if the number of attempts is exceeded#

{
    "instructions": [
        {
            "mobile":"79988984169",
            "name":"mbl-no-attempts"
        }
    ],
    "context":"kE6r…7g"
}

Request to initiate the re-sending of the code via SMS (specify any code as the parameter value)#

POST /blitz/reg/api/v3/users/YNx9…Dw HTTP/1.1
Authorization: Bearer cNw…Nz
Content-Type: application/json

{
    "sms_code_resend":"123456"
}

Response No.2

If all contacts were confirmed during the registration process, then as a result of calling the service, a user account with the provided attributes and password will be registered in Blitz Identity Provider. The service will return the user ID assigned to the account (subject). In addition, a number of service attributes (instructions, cookies and context) will be returned.

{
    "instanceId": "Yml…Yw",
    "subject": "BIP-1TZYWXQ",
    "context": "NIi…qQ",
    "cookies": [
        {
            "name": "css",
            "value": "t8_…84"
        }
    ],
    "instructions": []
}

Error

Registration may fail. Then there will be an explanation of the problem in the body of the response. In particular, if the uniqueness of an attribute is violated in Blitz Identity Provider, the message will contain a list of fields for which uniqueness is violated.

{
    "errors": [
        {
            "errMsg": "Такой пользователь уже зарегистрирован…",
            "field": "email"
        },
        {
            "errMsg": "Такой пользователь уже зарегистрирован…",
            "field": "phone_number"
        }
    ],
    "context": ""
}

Registration with a confirmed email and phone number with the transfer of a dynamic client_id

Request#

PUT /blitz/reg/api/v3/users HTTP/1.1
Authorization: Bearer cNw…Nz
Content-Type: application/json

{
    "user": {
        "attrs": {
            "sub": "BIP-9TZYWXQ",
            "family_name": "Иванов",
            "given_name": "Иван",
            "middle_name": "Иванович",
            "email": {
                "value": "ivan.ivanov@example.com",
                "verified": true
            },
            "phone_number": {
                "value": "79991234567",
                "verified": true
            }
        },
        "credentials": {
            "password": "Qwerty_123"
        }
    },
    "actions": [
        {
            "type": "bindDynClient",
            "client_id": "dyn~test-app~c84f26f3-10f3-4b85-a6ee-a4ca12c41d26"
        }
    ]
}

Registration in English

Request#

curl -v --location --request PUT 'https://demo.identityblitz.com/blitz/reg/api/v3/users' \
--header 'Content-Type: application/json' \
--header 'Accept-Language: en' \
--header 'Authorization: Bearer ...' \
--data-raw '{
    "user": {
        "attrs": {
            "sub": "username",
            "phone_number": {
                "value": "89101234567",
                "verified": false
            }
        },
        "credentials": {
            "password": "Qwerty_123"
        }
    }

}'