This guide assumes you've already done the following:
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:
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.
It is highly recommended that the key not be stored inside any client-side app or code as it can be easily extracted and abused.
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.
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.
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....'
environment_guid can found in the dashboard,
path_to_private_key is the location of the
.pem file from when you created the environment.
arbitrary_id is the identifier by which a user can be located in the Work-API system.
A user must:
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.
It is recommended that the string be non-identifying information to avoid data traversing the Work-API system being deanonymizable.
The Ruby SDK will generate an APT as part of the user creation process.
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...', ... )
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
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 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.
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: