Authentication

Basic usage

await uthentic.login();

The most basic usage of Uthentic is simply calling uthentic.login(). The login method will return a promise that is resolved when the login sequence is complete and the user's identity has been validated. The login method performs the following steps with no setup and no additional code.

1. Check to see if there is a user token on this device
2. If there is a user token, verify the token. If the token is valid, resolve the promise.
3. If there is not a user token, or if the token is not valid, show the login modal
4. Collect the user's email address
5. Send the user an email with a special login button
6. Wait for the user to click the button in the email
7. Resolve the promise

The user object

Whenever a user is logged in, you can access the uthentic.user object that contains information about the currently logged in user and the their account.

{
    "id": "0atMntshIh...", //unique 32-char identifier for this user
    "accountID": "ufUjO4I6tB...", //unique 32-char identifier for this account
    "token": "CXTaG5Vxvq...", //an encrypted token that identifies this user (see: Server-Side Auth)
    "profile": {
        "email": "john.doe@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "name": "John Doe"
    },
    "role": "Owner" //the Role of this user for this account
}

Client-side token validation

When a user logs in, Uthentic stores a token on their device. This token is valid for 34 days. Uthentic automatically validates the token in the background once every 15 minutes. If a user does not visit your site for 34 days, their user token will expire. When they visit your site again, they will have to log back in.

To force re-validation of a user at any point (such as when permissions are changed), you can call:

await uthentic.auth(true);

Server-side token validation

You can access information about the user in JavaScript via the uthentic.user object (more info). Of particula importance is the uthentic.user.token property. Once this value is passed to your backend, you can make an API call to Uthentic to verify the validity of the token, confirming that a user is actually who they say they are.

POST https://uthentic.net/api/v2020-10-25/validate-token
HEADERS: 
    x-secret-key={your-secret-key}
    x-auth-token={the-auth-token-of-your-user}
BODY:
    empty body

{
    "success": true,
    "accountID": "ufUjO4I6tB...",
    "userID": "0atMntshIh...",
    "emailAddress": "john.doe@example.com"
}

{
    "success": false,
    "error": "Unauthorized",
    "details": "User creds not for this app"
}

Helper methods

Uthentic provides a couple of helper methods that include x-app-id and x-auth-token headers containing the app id and the user's token, respectively.

var result = await uthentic.get(myURL);

var result = await uthentic.post(myURL, dataToPost);