Make sure to register for free to get an app token to use the interface.

Registration and Login

If a user with the name doesn't exist it will be created. In any case a login attempt will be triggered.

{
  error: boolean | string
  codeToken?: string
  // Is this user authenticating for the first time?
  registration?: boolean
  // Only returned for anonymous logins.
  token?: string
  id?: string
  uid?: string
}

The returned token that we call CODE_TOKEN can be used to verify a registration or login request later. It's possible to pass the ADMIN_TOKEN in which case the user will directly be registered without any verification. No token will be returned in this case, so this is mostly useful to migrate an existing user base.

It's also possible to update the name of an existing user with this route. Do this by sending the USER_TOKEN along with the new name: https://iltio.com/api/authenticate?name=NEW_NAME&token=USER_TOKEN. This will also trigger the verification flow.

When Anonymous Login is enabled for the root user associated with the APP_TOKEN it's possible to register users without a name. Using the update path a name can later be added so users can persist data between sessions.

Confirm Login Request

Once the user has received the 4 digit login code through mail or text this route should be called to verify the request.

{
  error: boolean | string
  token?: string
  jsonWebToken?: { token: string; expirationDate: string }
  userId?: string
  uid?: string
  encrypted?: boolean
  encryptionText?: string
}

This request will verify the request and also return a USER_TOKEN. Only a small number of attempts are possible before the associated CODE_TOKEN will expire.

Polling for Confirmation Through Link

This route can be used to verify whether the user has already verified the login request by opening the link sent through mail.

{
  error: boolean | string
  token?: string
  jsonWebToken?: { token: string; expirationDate: string }
  userId?: string
  uid?: string
  encrypted?: boolean
  encryptionText?: string
}

Once successful a USER_TOKEN will be returned.

Resend Code

If a code associated with a code token has never been attempted it's possible to resend another code, invalidating the previous one. This is useful if a user has not received a token after some time.

{
  error: boolean | string
}

Authorization

Verifies if the token belongs to a user and returns the user information if successful. Can be used to check if a stored token is still valid or to authorize a request on the backend.

{
  error: boolean | string
  role?: 'public' | 'user'
  id?: string
  uid?: string
  name?: string
  root?: boolean
}

Invalid tokens will not lead to an error, but simply return the public role without any user information attached.

Hasura Authorization Webhook

Header: x-token=USER_TOKEN

When this webhook is registered with hasura and the token is passed in the header it can be used to authorize users directly. The 36 characters long unique UID is used as the user-id.

{
  error?: boolean
  'X-Hasura-User-Id'?: string
  'X-Hasura-Role'?: 'user' | 'public'
  'X-Hasura-Is-Owner'?: 'false'
  'X-Hasura-Custom'?: string // name or 'anonymous'
}

Recovery Token

If enabled by the root user on the user page it's possible for any attached user to retrieve a recovery token. Using this same route a login can be performed with the recovery token returning a regular token allowing the user to login again.

{
  error: boolean | string
  recoveryToken?: string
  token?: string
}

Change - 🚧 Planned Interface

Allows a user to change the name which is used for authentication.

{
  error: boolean | string
}

Logout

Invalidates a token so that it can no longer be used to authorize.

{
  error: boolean | string
}

Remove User

Deletes the user that the token belongs to. If the name is provided along with the matching app token then that user is deleted. When using the user token from the owner account or the admin token, it's possible to delete any user by name.

{
  error: boolean | string
}

User

Retrieves the information for an authenticated user.

{
  error: boolean | string
  id?: string
  uid?: string
  encrypted?: boolean
  encryptionText?: string
}

Toggle Encryption

Toggles whether client-side encryption is enabled. This is merely a state flag that has no effect on any other backend logic as encryption only happens in the client.

When turning on make sure to also submit an encrypted text of the string "Hello Encryption" that can later be used to check if the correct encryption key was entered on the client.

{
  error: boolean
  encrypted: boolean
}

Add a Log

Once you have created an event by logging into iltio.com you can add logs through a POST request with the data in the body.

{
  error: boolean
}

List Logs

Listing logs requires a valid token from your iltio.com account. Generally, it's recommended to view your logs through the iltio.com UI.

{
  error: boolean
  logs: {
      id: number
      data: string | null
      createdAt: Date
  }[]
}

Get Auth0 Token

Get an Auth0 token for a user.

{
  error: boolean
  token: string
}