API

ID verification requests

After a successful login to the RamBase API an access token is generated and returned to the user. This token is used in all subsequent requests to ensure valid authentication. If anyone gets hold of this access token it can be used to impersonate the user, either by retrieving data or performing operations on behalf of the user. This is the reason why access tokens never should be shared with anyone!

In some cases, a third-party integration or system needs to know if there exists a valid session for a user in RamBase. Since access tokens should never be distributed, an ID verification token exists for this purpose. This token can be used to find out who the user is in RamBase, and which RamBase system they are signed in to.

Any user can retrieve the ID verification token by making a GET request to the current session.

The ID verification token can safely be sent to anyone. After retrieving an id verification token, you can make a GET request to the following URI:

GET https://api.rambase.net/id-verification?id_verification_token=q6SD0ZhQ0k6DO9-abcdefghijklmn

The following response is returned:

1
{
2
    'idVerification': {
3
        'user': {
4
            'userId': 666,
5
            'userLink': 'https://api.rambase.net/system/users/666?$format=json'
6
        },
7
        'ramBaseSystem': {
8
            'name': 'HATTELAND'
9
        },
10
        'customer': {
11
            'customerId': null,
12
            'customerLink': null
13
        },
14
        'supplier': {
15
            'supplierId': null,
16
            'supplierLink': null
17
        }
18
    }
19
}

A successful response tells that the provided ID verification token belongs to a user that is currently logged in to RamBase. The response contains information about who the user is and which RamBase system the user is logged in to. If logged into supplier- or customer portal, id of the supplier/customer is also provided.

Example of usage

A RamBase development partner has developed an AI engine that can predict sales based on the first name of a customer. They decide to create an extension in RamBase to make this available in the sales and operation planning module. They want to keep the algorithm safe and decide to create a REST service called ForecastRESTAPI which they develop and maintain themself. They do not want to use time on handling user management and making a secure authentication, which makes ID verification tokens is a perfect match!

This is how the extension works:

  1. A REX component is created with a text input for first name and a submit button. After filling the name and clicking the button, a list of forecasted sales orders should be generated and presented.
  2. When the user clicks the button in the REX component makes an API request to https://api.rambase.net/system/sessions/current with the user's access token to get an ID verification token.
  3. The first name from the text input, together with the received ID verification token, is then sent from the REX component to the ForecastRESTAPI to get the forecasted sales orders.

  4. The ForecastRESTAPI now receives a request with the first name and an ID verification token. The users access token is not received.
  5. Before creating a response with forecasted sales orders, they need to verify that the ID verification token is valid. To do that they need to make a request to the RamBase API for the verification. The RamBase team has provided them with a set of API client credentials which they use to authenticate to receive an access token.
  6. The ForecastRESTAPI uses this new access token to make a request against https://api.rambase.net/id-verification?id_verification_token=insert-id-verification-token. If the response is successful, they know that the id verification token belongs to a authenticated user and the forecasted sales orders is generated and returned. Also, the returned RamBase system and user id is logged in their own API request log.

  7. The REX component generates and presents the list of forecasted sales orders based on the successful response from the ForecastRESTAPI

Note that access tokens created for RamBase API is never sent anywhere else than to the RamBase API! The ID verification token can be shared with anyone.