Linking Identities Across Different Organisations

Users from one organisation can be invited into another organisation so that they are granted access to certain companies in the other organisation. In order to connect organisations, there are 2 basic steps that need to be completed:

• The inviter organisation needs to link the invitee organisation to their account
• Then, the inviter can grant access to any identities in the invitee organisation provided they have been given the 'public key' of those users by the invitee organisation.

Linking organisations together requires an organisation admin from both organisations. All actions are performed via API so both users will need to have setup a token and be familiar with interacting with MachShip via the API. All our API documentation can be found in our API Documentation.

For the remainder of the article we will use the following two terms:

• Inviter Organisation. This is the organisation that is granting another organisation's identities access to its account.
• Invitee Organisation. This is the organisation that is requesting access to another organisation's company.
• Organisation Administrator. This is a special role in MachShip and only an Organisation Administrator can perform the following steps in MachShip

Step 1. Invitee Organisation - Generate and Send Public Key

Every organisation in MachShip has a public key and this is an identifier that can be accessed for certain actions in MachShip. This key should be kept private and only shared with organisations that you wish to join. If the public key is compromised, you have the option of resetting your public key (note that this will not unlink you from any organisations that you are currently linked to).

The Organisation Admin from the Invitee Organisation can access their public key via the /apiv2/organisationLinks/getPublicKeyForOrganisation endpoint. Once retrieved, this should be securely sent to the Organisation Admin of the Inviter Organisation.

Step 2. Inviter Organisation - Link the Invitee Organisation to their Organisation

Once the Organisation Admin of the Inviter Organisation has the public key, they need to link the invitee organisation using that key. Note that organisation linking is single direction only. Once linked, identities from the invitee organisation can be added to the Inviter organisation, however the reverse is not allowed. To allow this, Step 1 and 2 would need to be completed in reverse.

The public key needs to be used in the /apiv2/organisationLinks/add endpoint. Once completed, identities from the invitee organisation can be granted access to the inviter organisation.

Step 3: Invitee Organisation - Retrieve Identity Public Keys

Now that the organisations have been linked, the Organisation Admin of the Invitee needs to get the public keys for all users that are being granted access to the inviter organisation. Again, the public keys for the identities should remain secure and only given to the organisation administrator for the inviter organisation. To get the public keys, you can get a list of all the user identities via the /apiv2/identities/getIdentities endpoint. You can then use the returned ids and pass them into the /apiv2/identities/returnIdentityPublicKeys endpoint. This will return you a list of the public keys and their corresponding identity Ids. These public keys should then be sent to the Organisation Administrator of the inviter organisation.

Step 4: Inviter Organisation - Add the identities to specific Company and Role

Once the Inviter Organisation Admin has the public keys, they can grant access to these identities via the user interface via Admin -> View Users -> Link Existing Entity modal. Alternatively, this can also be done via API using the /apiv2​/identities​/linkIdentitiesToCompanies endpoint. Either process takes the following:

• Public Key(s): this is the public key of an identity as provided by the Invitee
• Selected Company: This is the company that you are granting access to for the corresponding identity. Company ids can be retrieved from either the API or from the URL of the view companies page in MachShip
• Roles: Selected roles / an array of role ids that should be granted to the corresponding identity. Multiple roles can be specified. These ids can also be retrieved from either the API or from the URL of the view roles page.

Once complete, the linked identities will now have access to multiple companies in MachShip. A user can only access a single company at any one time. A user can switch between companies by going to the options at the top right corner of the MachShip UI and selecting 'Switch Company'.

See the flow below for the steps required to link organisations together