Machine to machine requests to the APIs

This document enrichs the How to access to the iObeya API section of the Facade API in case of a non end-user context - when the integration is performed directly by an external system and an OAuth 2.0 connection is not available. In that case, the OAuth handshake won't be possible by definition. That's why a dedicated setup has to be followed. In a nutshell, here are the steps:

One needs to create a dedicated user and generate an JWT token (Bearer) for this user. Create a dedicated iObeya user for the integration.

A platform administrator has to create a new iObeya account that will be used to perform the integration. For example, this user can be named "MyERP Integration". The capabilities of this integration - the permissions behind it - will be based entirely on the permission of that user.

Here is how to manage users in the iObeya administration.

The email address will be defined with the one of the current administrator for now. Refer to the section bellow to see the possible configurations once everything is defined. Let's call this user MachineUser for the purpose of this documentation.

Because the token will be associated with this user, it has to be created on its behalf.

So he has to be granted temporary:

1. Get the Administrate the platform permission
2. Get a password so it can be used locally to connect to the iObeya administration.

It is recommended to use a password generator like psswrdgnrtr to strongify the security.

1. Logout from the iObeya administration
2. Login with MachineUser
3. Generate a token as described in the getting started section of the Facade API documentation, but:
   • Because the handshake won't be performed in that context, the "Grant type" parameter has to be set to "Implicit authorization". Uncheck "Authorization code" and "Refresh token".

1. • Keep the generated callback URL. If no url is provided, make sure you have only "Implicit" checked.
   • Select the desired access token validity, between 1 minute and 365 days. As there is no possibility to use the oauth refresh token principle, we recommend to set the availability to 365 days, otherwise the token would need to be regenerated too frequently.

1. • Save the API application
   • Click on the button "Generate the token"

1. • Copy the token and save it safely as it won't be possible to get it again (it is still possible to regenerate a new one). And keep it secret, because this token embeds the permissions associated with MachineUser.
   • ✅ Now, the token can be used in the external client / application / script / machine in order to access the APIs

Now, MachineUser must be configured as a standard user as it does not require the permission to administrate the platform anymore (or only if his token has to be regenerated).

1. Login as a human platform administrator
2. Uncheck the Administrate platform permission on MachineUser
3. Give the necessary permissions on the rooms where integration has to be performed (it is also possible to ask the room administrators to add this specific user in their team in order to enable the integration)
4. Reconfigure the email in one of these ways:
   • With a non-existing email
   • With the email of the current iObeya administrator
   • With the email of a group of iObeya administrators

Optional: reset the password of MachineUser so no more local login is possible

Note

It is also possible to delegate the accountability of the permissions of MachineUser to the room administrators. Based on guidelines, they could own this part.

In an user point of view, it is possible to imagine something like "If you need / have to enable the integration, the user MachineUser has to be in the team of you room, with the relevant permissions"

• Machine to machine (External System to iObeya) integration with APIs is a specific situation that requires an Admin Access Token as described in the image above
• iObeya permission management relies on user accounts so a dedicated user is recommended in order to isolate and manage this integration
• API token are generated directly by a user with platform administration permissions:
  • The dedicated user must be granted temporary permissions to create its own token
• About the OAuth configuration, we use the standard OAuth 2 protocol
• Because of the direct connection performed by a machine, the token can't be refreshed automatically
• Because token can't be refreshed automatically, it must be granted as "implicit" so that it can have a maximum life duration of one year
  • →  At least every year, a platform administrator, on behalf of the machine user, must therefore regenerate the token because it will expire automatically - the integration won't work anymore
• Note that at any moment, a token can be revoked by any iObeya platform administrator

The generated token, associated with MachineUser can be used in any system, it fully depends on the integration requirements.

In any case, every request performed to the Facade API must provide a key Authorization in the header with the string "Bearer " followed by the token value as explained in the Facade API documentation.