For a detailed explanation of the REST interface, please refer to Loginapp REST API Reference.
This request starts the self-registration of a user. Since no flow is selected explicitly, the default flow is started.
Step 1 - HTTP request - user data registration step
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/data/ { "surname" : "Doe", "email" : "john.doe@ergon.ch", "town" : "Zürich", "birthdate" : "1970-10-01" }
A successful response will return a value of "USER_DATA_REGISTRATION_REQUIRED" if the call was successful but a call to continue would fail. Use the validate call to list all validation issues.
Step 1 - HTTP response - user data registration step
HTTP/1.1 200 OK { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2018-12-12T08:43:48.356Z" }, "data": { "type": "user-self-registration.session", "id": "509880836941347711", "attributes": { "nextStep": "USER_DATA_REGISTRATION_REQUIRED" } } }
Since the given name is mandatory, but was missing from the previous call, another call to the /data/ REST API is required.
Step 1 - HTTP request - user data registration step
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/data/ { "givenname" : "John" }
A successful response will return a value of "USER_DATA_REGISTRATION_POSSIBLE" if the call was successful and a call to continue will be successful as well.
Step 1 - HTTP response - user data registration step
HTTP/1.1 200 OK { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2018-12-12T08:44:33.047Z" }, "data": { "type": "user-self-registration.session", "id": "509880836941347711", "attributes": { "nextStep": "USER_DATA_REGISTRATION_POSSIBLE" } } }
This request is required to move the flow one step ahead.
Step 1 - HTTP request - continue
Since we already know that the validation was successful, the response should always be a 200 OK.
Step 1 - HTTP response - continue
HTTP/1.1 200 OK { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2018-12-12T08:50:39.232Z" }, "data": { "type": "user-self-registration.session", "id": "509880836941347711", "attributes": { "nextStep": "EMAIL_OTP_REQUIRED" } } }
Step 2 is non-interactive and does not require any REST calls to be executed.
When the email verification step is started, it first generates a message and sends it to the channel verification target (i.e. the email address) to be verified.
Email Message
Sehr geehrte(r) John Doe
Bitte bestätigen Sie die Registrierung mit Benutzername john.doe@ergon.ch mit diesem Code: umFWMZ4S.
Freundliche Grüsse, Ihr IAM-Team
In the user interface, the user is required to enter the code provided in the message to be entered.
Step 3 - HTTP request - email verification step
POST https://iam-host.com/auth/rest/public/user-self-registration/verification/email/otp/check/ { "otp" : "umFWMZ4S" }
Step 3 - HTTP response - email verification step
HTTP/1.1 200 OK { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2018-12-12T08:51:19.268Z" }, "data": { "type": "user-self-registration.session", "id": "509880836941347711", "attributes": { "nextStep": "USER_DATA_REGISTRATION_REQUIRED" } } }
Step 4 - HTTP request - user data registration step
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/password/ { "password" : "password0" }
Step 4 - HTTP response - user data registration step
HTTP/1.1 200 OK { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2018-12-12T08:51:44.996Z" }, "data": { "type": "user-self-registration.session", "id": "509880836941347711", "attributes": { "nextStep": "USER_DATA_REGISTRATION_POSSIBLE" } } }
This request is required to move the flow one step ahead.
Step 4 - HTTP request - continue
Since we already know that the validation was successful, the response should always be a 200 OK.
Step 4 - HTTP response - continue
HTTP/1.1 200 OK { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2018-12-12T08:52:02.237Z" }, "data": { "type": "user-self-registration.session", "id": "509880836941347711", "attributes": {} } }
After the continue, the user persisting step will be executed automatically.
In this request, the birthdate attribute contains incorrectly formatted input.
HTTP request - user data registration step with incorrect data
POST https://iam-host.com/auth/rest/public/user-self-registration/registration/data/ { "surname" : "Doe", "givenname" : "John", "email" : "jdoe@ergon.ch", "town" : "Zürich", "birthdate" : "1.1.1970" }
In case of an error (in the example below the formatting of the birthdate was incorrect) a detailed error message is returned:
HTTP response failure - user data registration step
HTTP/1.1 400 Bad Request { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2018-12-12T09:01:47.225Z", "nextStep": "USER_DATA_REGISTRATION_REQUIRED" }, "errors": [ { "code": "VALIDATION_FAILED", "source": { "pointer": "/birthdate" }, "meta": { "type": "jsonapi.metadata.validation.error", "detail": "WRONG_FORMAT" } } ] }
The validate REST call is strictly speaking optional, but it is rather helpful for a GUI client to provide the end-user with information on why a particular set of data was rejected by the registration flow validation.
Note: it is possible to issue this call as the first call in the flow. This would allow the GUI to dynamically indicate to the user, which fields are mandatory and must be filled without hardcoding and before the user submits the form.
HTTP Request: validate
The validation returns all "errors" that must be addressed before a continue to the next step in the flow is possible.
Note: a 200 OK return code implies that the validation was successful and the step can be continued. A 400 Bad Request is returned to indicate issues with validation.
HTTP Response: validate
HTTP/1.1 400 Bad Request { "meta": { "type": "jsonapi.metadata.document", "timestamp": "2018-12-12T08:55:38.700Z", "nextStep": "USER_DATA_REGISTRATION_REQUIRED" }, "errors": [ { "code": "VALIDATION_FAILED", "source": { "pointer": "/email" }, "meta": { "type": "jsonapi.metadata.validation.error", "detail": "REQUIRED" } }, { "code": "VALIDATION_FAILED", "source": { "pointer": "/givenname" }, "meta": { "type": "jsonapi.metadata.validation.error", "detail": "REQUIRED" } }, { "code": "VALIDATION_FAILED", "source": { "pointer": "/surname" }, "meta": { "type": "jsonapi.metadata.validation.error", "detail": "REQUIRED" } } ] }