API authentication

    There are several ways to authenticate requests made for Compound Registration:

    • Basic authentication
    • Authentication for trusted 3rd party clients
    • Bearer token

    Basic authentication

    Basic authentication is a simple method to provide the username and password when making a request.

    Example

    Let's consider the case when a client wants to retrieve a compound identified by "CXN132". In this case a GET request must be sent to

    https://yourhost.com/RegistryCxn/rest/structureService/registryStructure?id=CXN132

    To authenticate this request, the proper Authorization header must be added, containing the base64 encoded username and password pair.

    As an example when the username is "tom" and the password is "password" then the header can be generated

    • on linux with bash
    echo -n "tom:password" | base64
dG9tOnBhc3N3b3Jk
    • on windows with powershell
    [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("tom:password"))
dG9tOnBhc3N3b3Jk
    • or alternatively this web tool could be used

    The full example with "Authorization" in the request header:

    GET https://yourhost.com/RegistryCxn/rest/structureService/registryStructure?id=CXN1 HTTP/1.1
Authorization: "Basic dG9tOnBhc3N3b3Jk"

    Authentication for trusted 3rd party clients

    The authentication for trusted 3rd party clients is based on basic authentication but it requires additional HTTP headers to be sent to Compound Registration. If you don't have a client and secret pair, you can check how to create one at here.

    To construct the authenticated request, you will need a username and a client, secret pair:

    1. Grant-Type: client_credentials

      This header tells the server, that this call should use the trusted 3rd party authentication method

    2. Reg-User: <username>

      This header contains the delegated username. It must be the username of an existing user in Compound Registration. The application impersonates this user and will use this value for submission/compound metadata (submitter, created_by, modified_by) and also will use the user's permissions, including project based access.

    3. Authorization: <encoded_credentials>

      This header is the base64 encoded value of the client:secret pair. See the previous example about encoding at basic authentication

    Example

    Using the previous example, a client wants to retrieve a compound identified by "CXN132". The client is eln-integrator, the secret is ZoXKWhjNQy and the impersonated user is tom. In this case a GET request must be sent to

    https://yourhost.com/RegistryCxn/rest/structureService/registryStructure?id=CXN132

    with the base64 encoded value of eln-integrator:ZoXKWhjNQy, that is ZWxuLWludGVncmF0b3I6Wm9YS1doak5ReQ== in the "Authorization" header, tom in the "Reg-User" header and client_credentials in the "Grant-Type" header. The request would look the following:

    GET https://yourhost.com/RegistryCxn/rest/structureService/registryStructure?id=CXN132 HTTP/1.1
Grant-Type: client_credentials
Reg-User: tom
Authorization: Basic ZWxuLWludGVncmF0b3I6Wm9YS1doak5ReQ==

    Bearer token

    The bearer token is a type of access token used in authentication and authorization processes. It is issued by an authentication server after a successful login or authentication process and is sent by a client to a server to access protected resources or services.

    SaaS Compound Registration uses dedicated Identity and Access Management (IAM) services to authorize and log in users. If you have access to the demo environment, you can open https://demo.synergy.cxn.io/resources/apikey in the browser and receive a token after logging in. For a limited time you can use this token to make API calls to Compound Registration within the demo environment. To get a bearer token for a different environment, navigate to the Synergy or Chemaxon Cloud dashboard and append the /resources/apikey to the end of the URL. For example https://yourclientname.cloud.chemaxon.com is the Chemaxon Cloud dashboard URL, then you can receive a bearer token at https://yourclientname.cloud.chemaxon.com/resources/apikey

    Example

    Similarly to the previous examples, the client wants to retrieve a compound identified by "CXN132".

    First, the user has to retrieve a bearer token from Chemaxon Cloud at https://yourclientname.cloud.chemaxon.com/resources/apikey and copy the value from the browser. This will be used as the "Authorization" header by adding the Bearer and a space character before the token. Now the request can be constructed as:

    GET https://yourhost.com/RegistryCxn/rest/structureService/registryStructure?id=CXN132 HTTP/1.1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6InRvbSIsImlhdCI6MTUxNjIzOTAyMiwiZXhhbXBsZSI6dHJ1ZSwiZ3JvdXBzIjpbIlVTRVIiLCJSRUdJU1RSQVIiXX0.9ELmKbEV6Aqdkw3hdSH-dS4edgnTjzNU7ZqN_fuqSuI

    Summary

    Basic authentication Authentication for trusted 3rd party clients Bearer token
    Where can it be used? On-Prem On-Prem, SaaS SaaS
    When to use it? For setting up API tools (such as Postman) when Compound Registration uses Database, AD, LDAP authentication Use this method if you need an API key for service integration or to set up API tools when Compound Registration uses SAML It is a quick and easy way to set up API tools for SaaS Compound Registration
    User synchronization Not needed Not available, the user has to exist in Compound Registration The user is synchronized based on the token

    More examples on how to construct an API call can be seen in the payload of developer console in your browser. You can have more info here.