Core - User =========== .. Last update: 04/04/2022 The base url for the APIs in this page is at:: /api/mobile/ A JSON file with OpenAPI data about all core-related mobile APIs can be downloaded :download:`here `. Login ----- Login is handled via the `/v1/user/mobile-logon` endpoint: .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/mobile-logon The object to pass to this API is like this:: { Username: "username@username", // String (Required) Password: "thepassword", // String (Required) SmBrand: "smartphone Brand", // String SmModel: "smartphone Model", // String OsName: "Smartphone OS Name", // String OsVersion: "Smartphone OS Ver", // String AppName: "App Name", // String AppVersion: "App Version" // String } All fields apart the ``Username`` and ``Password`` are optional, and are recorded together with session data for description and troubleshooting purposes. The resulting object is like this:: { MustChangePassword: true // Boolean Token: "a valid JWT string", // String Roles: ["array","of","role","slugs"], // String Array Name: "The registered first name of the user", // String Surname: "The registered last name of the user", // String FullName: "The registered full name of the user" // String } The ``MustChangePassword`` field means that the user should be forced to change password The ``Roles`` and ``FullName`` fields may be used by the UI/UX to immediately hide/enhance the functions that may be accessed by the user. In case of errors, the ``Message`` values that Movens may report are: ``err_InvalidCredentials`` When the credentials supplied cannot be matched to any registered user. ``err_CannotAccess`` The user has been successfully identified, but cannot access now. This may be due to user having been blocked, not being confirmed (e.g. via a link in an e-mail message that must have been clicked), or not having enough roles to access the mobile endpoints. ``err_TooManySessions`` The user has reached the maximun allowed number of concurrent sessions Logout ------ Logout is handled via the `/v1/user/logoff` endpoint: .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/logoff The API does not need any object provided, and it will logoff the current active session for the user. Registration ------------ The endpoint .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/register can be used to register new users. The object to supply has this form:: { Email: "mail@address", // String MobilePhoneNumber: "123 4567890", // String Password: "chosenpassword", // String, minimum length 8 characters Community: "ABCDEFGHIJK", // String (Registration Code) Language: "en-US", // String Name: "The User Name", // String Surname: "The User Surname", // String PrivacyAgreement: true, // Boolean TermsAndConditions: true // Boolean } Where only the ``Language`` field is optional, and will default to the invariant culture, that will produce English localization from the server. A successful registration will produce the forwarding of an e-mail message to the user, to validate the new account, and will return a positive response without data. The resulting object if the registration is successful is like this:: { Token: "a valid JWT string", // String Roles: ["array","of","role","slugs"], // String Array FullName: "The registered full name of the user" // String } The ``Roles`` and ``FullName`` fields may be used by the UI/UX to immediately hide/enhance the functions that may be accessed by the user. Note: the JWT string issued by this endpoint *cannot be renewed* and will be invalidated upon expiration. User Agents should use it only to gather further information from the user and store it e.g. as custom fields, and should instruct the user to check the e-mail message and perform a login at the end of the registration workflow. Should an error happen, the negative result will have one of these error messages: ``err_AlreadyRegistered`` Means that the e-mail address is already in use by an account that has been confirmed. Note that this may lead to leaking information about an user existing. ``err_InvalidCommunity`` The supplied Guid for the community cannot be found as an active community in the system. ``err_UnbelievableEmail`` The supplied e-mail address is shorter than 3 characters, or does not contain an '@' symbol, or does not contain at least one dot. This check is not RFC-5322 compliant, just to help prevent totally invalid strings. ``err_InvalidPasswordLength`` Password is rejected if shorter than 7 characters. UI/UX implementations should encourage longer and unique passwords on their own. ``err_UnableToSendEmail`` The system was not able to queue an e-mail message for delivery to the specified address. ``err_NoPrivacyAgreement`` No PrivacyAgreement or TermsAndConditions data has ben provided, or they have been set to false ``err_InvalidUserdata`` One or more mandatory additional user data was not provided or was invalid Validate a user --------------- Marks a user as validated during the registration procedure .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/validate/{userId}/{actionToken} The request will redirect the user to a different destination on success/failure. Unregister ---------- The endpoint .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/unregister can be user to revoke a user registration. The object to supply has this form:: { Username: "mail@address", // String Password: "chosenpassword" // String } Should an error happen, the negative result will have one of these error messages: ``err_InvalidRequest`` No username or password was provided ``err_InvalidCredentials`` The provided username and password does not match Renew Token ----------- Renew the token for the currently authenticated user: .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/token-renew If the request is successful it will return the new token. If not a generic json error message will be returned. Password Recovery ----------------- An user can request a password recovery simply specifying the username/e-mail address. .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/recover-password The format of the request object is this:: { Username: "email@address" } If the user exists and is available, the server will forward an e-mail message with a password reset link inside; the password reset form `must be provided by the implementator and included inside the e-mail message template`. The errors that may happen are described by these messages: ``err_InvalidRequest`` The username is empty ``err_UnableToSendEmail`` The username may not exist, have been disabled, have an invalid e-mail address, or a temporary problem with e-mail delivery may have happened. Password Reset -------------- Completes the password recovery (reset) workflow for the given username, only if the token matches: .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/confirm/reset-password The format of the request object is this:: { Username: "username", // String Password: "password", // String Token: "a valid token" // String } The ``Token`` property has to be set with the action token provided in the password reset link sent by the password recover API. Possible errors are described by these messages: ``err_InvalidRequest`` Any of the required fields is empty or null, or the provided password is less than 8 characters ``err_NoSuchUser`` No user matching the username was found or an invalid token is provided ``err_SamePassword`` The new password provided is the same as the old one Subscribe to community ---------------------- Use this endpoint to subscribe the user to a community. .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/community-subscribe The object to supply has this form:: { Community: "ABCDEFGHIJK", // String (Registration Code) } After successfully subscribing the user to the new community, the API will return a new JWT token and invalidate the previous one:: { Token: "the new token" } Possible errors are described by these messages: ``err_InvalidCommunity`` The provided registration code does not map to any existing community Unsubscribe from community -------------------------- Use this endpoint to unsubscribe the user from a community. .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/community-unsubscribe The object to supply has this form:: { Community: "753a5f64-70df-445d-97e2-43afc704a767", // Guid } After successfully unsubscribing the user from the community, the API will return a new JWT token and invalidate the previous one:: { Token: "the new token" } The API will return a plain error message if problems occurred while removing the community (i.e. the provided community is the only one the customer is subscribed to), or one of the following: ``err_InvalidCommunity`` The provided guid does not map to any existing community the user is subscribed to Get current user master data ---------------------------- Use this endpoint to retrieve the full master data object for the current user (i.e. the user owning the current Authorization token). .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current Response example:: { Name: "John", // String Surname: "Doe", // String FullName: "John Doe", // String Roles: ["Role A","Role B"], // String Array UserName: "user@email.com", // String Email: "user@email.com", // String MobilePhoneNumber: "0123456789", // String CreatedDate: "2001-01-01T01:01:01Z", // DateTime FCMTokens: ["b6486c40-c5a8-428c-a7be-995df0513dbe",..] // String (nullable) LCID: 100, // Int Language: "en-US", // String AvatarImage: "013d7d16d7ad4fefb61bd95b765c8ceb..." // ByteArray as String (nullable) Communities: [ { Guid: "53155c4a-b2a0-412f-ab41-552d9ccdf784", // Guid Name: "Community", // String PrimaryColor: 123456, // Int (nullable) AccentColor: 123456, // Int (nullable) Logo: "AAAAAAAAAA==", // ByteArray as String (nullable) Details: { Key: "detail-key", // String Value: "value" // String } }, ... ], ActiveSessions: 4, // Int, currently active sessions count IsDisabled: false, // Boolean IsDisablesByAdmin: false, // Boolean IsDisabledBySystem: false, // Boolean OverriddenSystemDisableStatus: false, // Boolean SystemDisabledReasons: ["No payment data", ...], // String array (nullable) Agreements: { TermsAndConditions: true, // Boolean TermsAndConditionsDate: "2021-01-01T00:00:00Z", // Datetime (nullable) PrivacyData: true, // Boolean PrivacyDataDate: "2021-01-01T00:00:00Z" // Datetime (nullable) } } ``AvatarImage`` is a base64-encoded image. ``FCMTokens`` is the array of identifiers for the FireBase channels in which the notification for the user are sent. Community data includes a base64-encoded logo image, and primary/accent colors as integer values. Get current user disabled status -------------------------------- Use this endpoint to retrieve the full master data object for the current user (i.e. the user owning the current Authorization token). .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/disabled-status Response example:: { IsDisabled: false, // Boolean IsDisabledByAdmin: false, // Boolean IsDisabledBySystem: false, // Boolean OverriddenSystemDisableStatus: false, // Boolean SystemDisabledReasons: ["No payment data", ...] // String array (nullable) } Update current user data ------------------------ .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/full-name With a body like this:: { Name: "John", Surname, "Doe" } It will return a plain negative response if no name or surname has been provided. .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/avatar-profile With a body like this:: { Base64String: "base64-encoded content of the file" } .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/password With a body like this:: { Password: "newpassword" } The API will also renew the current token, and will return the new token value:: { Token: "a valid JWT string", // String } Possible errors are: ``err_SamePassword`` The new password provided is the same as the old one ``err_InvalidPasswordLength`` The new password provided is shorter than the min accepted length of 8 characters .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/email With a body like this:: { Email: "newmail@mail.com" } It will return a plain negative respose if no email has been provided. Possible errors are: ``err_SameEmailAddress`` The new email address provided is the same as the old one .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/confirm/email Completes the e-mail address modification process. The API expects to receive both ``userguid`` and ``token`` in the query parameters. If the guid matches an existing user and the token is valid, the user will be redirected to a URL. Errors will return a 400 Bad Request response if no user has been found for the provided userguid, the provided token does not match to a valid token or no pending email address value is set for the provided user. .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/mobile With a body like this:: { MobilePhoneNumber: "9876543210" } It will return a plain negative response if no mobile phone number has been provided; Possible errors are: ``err_SameMobileNumber`` The new mobile phone number provided is the same as the old one .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/confirm/mobile Completes the mobile phone number modification process. The API expects to receive both ``userguid`` and ``token`` in the query parameters. If the guid matches an existing user and the token is valid, the user will be redirected to a URL. Errors will return a 400 Bad Request response if no user has been found for the provided userguid, the provided token does not match to a valid token or no pending mobile phone number value is set for the provided user. .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/language/{language} If the request is successful, a positive response will be returned. If there is a problem retrieving the current user, a negative Json response will be returned. Other errors that may happen are described by these messages: ``err_LanguageNotSet`` No language was set in the query parameters ``err_NoSuchCulture`` A non valid (null) or not recognized ISO3166 culture code was provided by the request All of these operations (unless otherwise specified) produce just a positive or negative response without any further indication. When updating the e-mail address or the mobile phone number the server sends a message, via a system-defined channel, to the user with a link to visit to complete the update. Update user agreements ---------------------- .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/agreements With a body like this:: { TermsAndConditions: true // Boolean } Edits the user's agreement. Might return a generic error if no previous agreement data has been found on the user or if no ``TermsAndConditions`` property has been provided, or one of the following error messages: ``err_CannotRemoveAgreement`` The term and conditions agreement has already been given, and no update has been allowed Add FCM token ------------- .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/fcm-token With a body like this:: { FCMToken: "b6486c40-c5a8-428c-a7be-995df0513dbe" } Add a new FCM device token for the current user except when the token already exists. The API will return a plain positive Json response or a generic error if no token is provided or if an error occurs. Delete FCM token ---------------- .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/fcm-token With a body like this:: { FCMToken: "b6486c40-c5a8-428c-a7be-995df0513dbe" } Remove a FCM device token for the current user. The API will return a plain positive Json response or a generic error if no token is provided or if an error occurs. Remove current user ------------------- .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/remove With a body like this:: { Password: "actualpassword" } Only the ``Password`` property of the posted JSON object is read. For convenience, User Agents may post other data (i.e. serialize an entire User object). User Agents should **not** send a stored user password but ask it upon starting the deletion procedure, to confirm the user's intention. Synchronize Custom Fields ------------------------- Users may have customizable fields added to them. To synchronize them with the server, this endpoint can be used. .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/fields/sync With a body like this:: { Fields: [ { Key: "fiscal-code", CurrentValue: "123ABC987XYZ" } ] } The server will receive and store the value of configured fields, and will return to the User Agent the list of all actual fields (and values), and the list of errors that arise while saving the data:: [ Fields: [{ Key: "fiscal-code", // String Labels: "{\"en\":\"Fiscal Code\"}", // String DescriptionLabels: "", // String ValidValues: "", // String ValidValuesLabels: "", // String ValueType: 2, // Int IsRequired: true, // Boolean CurrentValue: "123ABC987XYZ" // String }, ... ], Errors: [{ Field: "Birth date", // Localized field name Code: "10101", // Numeric code of the error Message: "..." // Localized description of the error }, { ... } ] ] The error reason may be: * 30000: the field is marked as required but no value has been provided * 30001: the field value is not valid as per the related additional user data field settings It may also return a plain error response if one of the provided fields has the ``Key`` property missing or empty. The ``Labels`` property contains a JSON dictionary that must be separately parsed. In the dictionary there is the proper translation, for available IETF language tag, of the meaning of this filter. In the ``ValidValuesLabels`` property there is a context-dependent JSON dictionary that must be separately parsed by the User Agent. In the dictionary, for each valid value, there is the proper translation, for available IETF language tags, of the meaning of such value. Value types can be one of the :ref:`enum-additionalvaluetypes` enumeration. Attachment fields have a ``CurrentValue`` of the attachment Guid; storing a new value requires using a different endpoint. Storing an Attachment custom field ---------------------------------- To store an Attachment-type custom field value, the User Agent must use this endpoint. .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/fields/attachment-field With a request body like this:: { Key: "user-selfie", // String Data: "AAAAAAAAAAA==", // String Name: "selfie1.jpg", // String MimeType: "image/jpeg" // String } Where in ``Data`` there is the Base64-encoded content of the file. The server will receive the data, store it, and return a positive response upon success and a negative response if the file cannot be stored. Inside the ``Data`` field for the positive response there is the Guid referring to the stored attachment. Get current user statistics ---------------------------- Use this endpoint to retrieve trip summary data for the current operator Number of trips, seconds of travel, km traveled .. openapi:: /openapi/srv-core/api-src-WebMobile.json :paths: /v1/user/current/statistics With a body like this:: { fromDate: "2012-04-23T18:25:43.511Z", // DateTime (nullable) toDate: "2012-04-23T18:25:43.511Z" // DateTime (nullable) } The API will automatically set both fromDate and toDate to have a max time span, as defined in the :ref:`configuration variable` ``MAX_STATISTICS_DAYS``, with priority on the end date. The API will respond with a plain error response if one or both the dates are in an invalid format or if toDate is inferior of fromDate, or with a positive response in the following format:: { TripCount:44, // Int SecondsTraveled:17580, // Int KmTraveld:100 // Int }