{{label:productName}} :: Docs :: Developers

Documentazione per sviluppatori app

La documentazione di {{label:productName}} è disponibile solo in inglese.

Cambi lingua (in alto a destra) per visualizzarla.

Client App operations documentation

This page describes the interaction between client app (or web manage interface) and {{label:productNameTxt}}.

The whole traffic between application server and {{label:productNameTxt}} server occurs under HTTPS.

General rules:

• URL: https://fastauthentication.org/manage:js/lpublic=public-token
• Method: POST
• Content-Type: application/json
• POST data: JSON, UTF-8 encoded
• JSON data must always include:
  • “lprivate” key
  • “lmethod” key, with operationName method
  • “jparams” key for operationName operation parameters, if required.
• All operationName methods return a JSON: updated session status, or an error object: {"error":"description"}

lpublic parameter is the client public key, or web-based manage session.
In case of web-based manage sessions it’s replaced by “FA-manage-session” cookie value.

lprivate is client app private key, or private key for web-based manage session.

About client security

Private data belonging to the session that could barely affect security never travel to clients.
Clients are assumed to be insecure.
They can authenticate themselves as a person with a key provided by web user profile management, and that’s it.
Each sensitive operation (e.g.: adding an identity) must be verified and processed serverside.

Beware of insecure clients, of course!
Despite of the fact that a malicious or insecure client can’t violate your profile security, as well as cannot add identities to your profile without verification, an insecure client could in any case be a tool that someone uses to authenticate as you.
A malicious client could send somewhere else its own private keys, even if there are protection mechanisms server-side that prevent this, including a notification system.

The status

As stated above, all operations return a JSON: updated session status, or an error object: {"error":"description"}

In case the session status is returned, it’s shaped like this:

{
	"lastupdate" : 1574686686,
	"person": {
	 	kperson": "11",
	 	jprefs": {},
	 	"lname": "Hohn Doe",
	 	"tlastseen": "2019-11-25 13:58:06",
	 	"kcount": "223"
	},
	"identities": [
		{
			"jidprefs": {},
			"kcount": "1",
			"kcustomer": "0",
			"kidentity": "15",
			"kperson": "11",
			"kprivate": "0"
			"kshared": "1",
			"ldisplay": "john.doe@mail.com",
			"lidentity": "john.doe@mail.com",
			"ltype": "mail",
			"tlastseen": "2019-11-25 11:46:00",
		}, {
			"jidprefs": {},
			"kcount": "7",
			"kcustomer": "0",
			"kidentity": "125",
			"kperson": "11",
			"kprivate": "1"
			"kshared": "0",
			"ldisplay": "#johndoe",
			"lidentity": "twitter:12345@johndoe",
			"ltype": "twitter",
			"tlastseen": "2019-11-25 13:58:06",
		}
	]
}

• lastupdate is unix time of last status update.
• person is the user object
  • person.jprefs is a JSON object, feel free to use it to store user-related preferences.
    Its limit is 8KB (for serialized UTF-8 JSON objects).
    Please consider it could be shared with other front-ends (e.g.: web interface).
    If you’re going to store you app preferences create your own key for it, eg:
    user.jprefs.myAppName = { … }
• identities is always an array of identity objects.
  Can’t be empty, because {{label:productNameTxt}} profile management authenticates through itself, therefore at least one identity must be defined.
  It’s an array in any case, also with one only element.
  • identity is the individual identity object you can manage.
    • identity.jidprefs is a JSON object, feel free to use it to store identity-related preferences.
      Same limits and considerations used for person.jprefs.

Fields like person.jprefs and identity.jidprefs don’t play any role in security and/or authentication.
They’re solely and entirely devoted to UI management and related preferences.

Methods

The JSON posted to https://fastauthentication.org/manage:js/lpublic=public-token looks like:

{
	"lprivate":"b6abf2d6ba9431a6416fa9ff",
	"lmethod":"username",
	"jparams":{
		"lname":"John Doe"
	}
}

A list of available methods of management (lmethod), and their params (jparams), if any.

“addid”

Request to add a digital identity (non-custom) to user profile.

jparams keys:

• lidentity: string, the display name of the identity: mail address, @telegramName, #twitterName
• ltype: string, enumerated typoe of identity, eg.: “mail”, “telegram”, “twitter”.

For ltype in “mail”, “twitter”

This won’t actually add the digital identity, but is mandatory before addidverify can be invoked.

For ltype = “telegram”

Again the method doesn’t actually add the identity, it a necessary prerequisite but addidverify won’t be used.
After this request message the Fast Authentication Telegram BOT and paste lpublic string, using the same @telegramName you declared in lidentity.

To make life easier for the user you can also use telegram’s deep linking, creating a link like:
tg://resolve?domain=Telegram BOT name&start=lpublic
or passing through the browser:
https://t.me/Telegram BOT name?start=lpublic

“addidverify”

Verify the identity and add it to user profile if successful-

jparams keys:

• lidentity: string, the display name of the identity: mail address, @telegramName, #twitterName
• ltype: string, enumerated typoe of identity, eg.: “mail”, “telegram”, “twitter”.
• lverify: string, the challenge text sent to the identity.

This method actually adds the identity to usere profile.

“logout”

Logout profile management session.

jparams is not applicable (ignored).

“rmid”

Remove the digital identity from user profile, and deletes the identity from Fast Authentication.

jparams keys:

• kidentity: numeric, the unique identity id.

“setidflags”

Set the “private” and “shared” flags for a non-custom identity.

jparams keys:

• kidentity: integer, must belong to the user in session.
• kprivate: 0 or 1, false or true.
• kshared: 0 or 1, false or true.

“status”

A void operation that simply returns session status.

jparams is not applicable (ignored).

“username”

Set person public name (first name and last name).

jparams keys:

• lname: string, first name and last name.