Overview

In order to create an account, the developer must issue a signed request that verifies a user/application has permission to do so.

This does the following:

• ensures the user is creating an account via the developer's app/platform
• provides reasonable assurance that the user's actions on the platform can be tracked for billing purposes
• reduces the possibility that a malicious user can abuse the system

User model

See the reference section for User model.

Creating a User on the new Environment

The creation of a new user account requires the developer to generate an Account Provider Token (APT). This is a simply a JWT that has been encrypted and signed using the environment's private key.

We recommend that the developer creates the user account via their own backend application rather than creating the Work API user account from the client application. This gives the developer full control over account management and ensures the private key is not exposed.

Generating an APT

If you are making a user creation request via the Ruby SDK, you can skip this section and jump to 'Creating the user'.

To generate the APT, you use your private key to sign the payload of a JWT.

Example

 apt = LivilApi::AptGenerator.generate_apt(
  environment_guid: '123456-1234-5678-12345679', 
  path_to_private_key: '/path/to/my-key.pem',
  arbitrary_id: 'user_xyz123',
  expiry: 10 # ttl in seconds, optional, default: 60s
)

apt 
# => 'eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE1ODQxMTQyNzQsImlhdCI6MTU....' 

The environment_guid can found in the dashboard, path_to_private_key is the location of the .pem file from when you created the environment.

The arbitrary_id is the identifier by which a user can be located in the Work-API system.

Creating the user

A user must:

• be assigned an arbitrary_id
• belong to an environment
• be created using an APT

What is an arbitrary_id?

An arbitrary_id is a unique field within the envirnoment which is used by the developer to reference the user.

It can be any arbitrary string of which the developer has an external and persistent copy. For example the user's acconut ID from the developer's database.

The Ruby SDK will generate an APT as part of the user creation process.

Example

         environment_guid = '123456-1234-5678-12345679'
path_to_private_key = '/path/to/pkey.pem'
arbitrary_id = 'user_xyz123'

client = LivilApi::Service.new
user = LivilApi::User.new(environment_guid: environment_guid, arbitrary_id: arbitrary_id)
created_user = client.create_user(user: user, path_to_private_key: path_to_private_key)

created_user
# => LivilApi::User(arbitrary_id: 'user_xyz123', token: 'eyJhbGciOiJSUzI1NiJ9...', ... )
        

Before expiration

A user's JWT will expire after (TBD). While it is still valid, the client app can refresh the user token simply be making a request to the /users/me endpoint.

Example

token = '<user token>' # stored when creating the user, or when previously refreshing the token

client = LivilApi::Service.new(token)
current_user = client.get_user

current_user
# => LivilApi::User(arbitrary_id: 'user_xyz123', token: )

# new token should be stored

After expiration

After expiry, a token must be reissued by the account provider using the APT. The process is very similar to reating a user, with the APT being generated under the hood when using the SDK.

Example

environment_guid = '123456-1234-5678-12345679' # the GUID of your environment
path_to_private_key = '/path/to/pkey' # the location of your .pem
arbitrary_id = 'user_xyz123' # the unique string you use to identifiy your user

client = LivilApi::Service.new
user = LivilApi::User.new(environment_guid: environment_guid, arbitrary_id: arbitrary_id)
reauthd_user = client.reauth_user(user: user, path_to_private_key: path_to_private_key)

reauthd_user
# => LivilApi::User(arbitrary_id: 'user_xyz123', token: )