Workspace authentication

In today’s interconnected world, secure authentication mechanisms are crucial for machine-to-machine (M2M) integrations to ensure the confidentiality, integrity, and availability of data. In Synerise, M2M integrations are handled by Workspace API keys. In each Workspace, you can create multiple API keys with different permissions.

Two commonly used methods for API authentication are:

• JSON Web Tokens (JWT): this is the default method for authenticating request made when using a Workspace API key. In this scenario, the API key is used to generate a JWT that expires after some time (60 minutes by default)
• API keys (Basic authentication): this is an additional method for authenticating as a Workspace that needs to be enabled separately in the settings of an API key. The GUID of the workspace is used as the login, and the API key as the password. This authentication doesn’t have an expiration time.

This article explores the differences between these two approaches, compares their features, and highlights the ideal usage scenarios for each variant. By understanding their advantages and disadvantages, developers can make informed decisions to implement robust and secure authentication mechanisms.

API authentication with JWT

JWT are a compact, self-contained, and digitally signed authentication mechanism. They are commonly used for stateless authentication in distributed systems.

A JWT token consists of three parts: a header, a payload, and a signature. The header contains information about the token’s signing algorithm, while the payload contains relevant user or client data. The signature is generated using a secret key and ensures the token’s integrity.

In Synerise, the token is generated for you when you authenticate as a workspace. You don’t need encode/decode it, or manipulate any data that’s included in the token. When you use the token to authenticate a request, Synerise decodes it and checks if that token grants the authorization for the operation you’re trying to perform.

Advantages

• Stateless: JWTs do not require server-side storage, making them suitable for scaling and load-balanced environments.
• Flexibility: JWTs can carry custom data in their payload, allowing for additional information beyond authentication.
• Granular Authorization: Tokens can include claims and scopes to control access to specific resources or functionalities.

Disadvantages

• Token Revocation: Since JWTs are stateless, revoking a token before its expiration requires additional mechanisms, such as maintaining a token denylist or short token expiration periods.
• Token Size: JWTs can be larger in size compared to API keys, leading to increased bandwidth consumption.

Usage

1. Obtain a JWT from the workspace authentication endpoint:
   

   curl --request POST 
   --url https://{SYNERISE_API_BASE_PATH}/uauth/v2/auth/login/profile 
   --header 'accept: application/json' 
   --header 'api-version: 4.4' 
   --header 'content-type: application/json' 
   --data '{"apiKey":"01234abc-1234-5678-9abc-def012345678"}'

   
   The response is a JSON Web Token (JWT) that must be included in the Authorization header of further requests. By default, the token is valid for 60 minutes.
2. Include the token (preceded by "Bearer") in the Authorization header of the requests you make, for example:
   

   curl --location 'https://api.synerise.com/v4/events/custom' \
   --header 'Authorization: Bearer eyJhbGciOiJSUzUxMiJ9.eyJzdWIiOiJjYTQzMTA4ZGVkNWFhYmM3NzkzZDNmOWI5MjhjZGQ1NCIsImF1ZCI6IkFQSSIsInJsbSI6ImJ1c2luZXNzX3Byb2ZpbGUiLCJjdGQiOjE2ODY3NDEyNzE2NTIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjoyMzcwLCJzZXNzaW9uSWQiOiI3MjIzMTgzMC02ZDVhLTQwNGUtYjVlMy1hMTZlMDkxNzcyODIiLCJleHAiOjE2ODY3NDQ4NzEsImFwayI6ImFlZTM0NzdiLTY0YWItNDFkYy1iMThjLWRhMjQwZmI0ZjdlYyJ9.w9p94Owhdygw7w4EnZnA1nDXQCFyMinvalidANNobb4vukXFtsb_gCAyxCFpS35SDctCtzgMXKetNErhEJKrovrOhlQ2GhxvuAHDf_Rz8EawlEiSuPvaUV0djfqJdZujkD1wPPylRj2neqFy6El5D3gsqByKRZMVekackbmjTr8KQMbfiddeUtZPtIoDcSxsv6SozRruCNjEulczc4Tgn44Ht7ZhiNJDPTfyR2nINcTfuBdMngDG5ye39QzwW7WAgLxKerBKIwS34Ul10gpUD11UJebtGc9B16WWmlXD5iY90HR6cjiexSQ1kTcjkA3yQgVkyNXrRF2e1mpM5cXbWfvcyh0_W-U-kUfRFu4DQcYIvh5M4nT4eiC4RsxsoeJSUEhvfg7bLe085w_ug_f1PBCxiHM' \
   --header 'Api-Version: 4.4' \
   --header 'Content-Type: application/json' \
   --data '{
       "action": "auth.test",
       "client": {
           "id": 6501571767
       },
       "params": {
           "test": true
       },
       "label": "string"
   }'

Basic API authentication with API keys

You can configure a Workspace API key to be used as a password (the workspace GUID is the login) for basic authentication.

The login/password combination is encoded with base64 and the result is sent in the Authorization header of an API request.

This authentication doesn’t have an expiry date and doesn’t need additional API calls to obtain JWTs (but the API key can still be used to generate them as described earlier).

Advantages

• Simplicity: API keys are straightforward to implement, making them an ideal choice for simple integrations or quick prototyping.
• Easy Revocation: You can revoke access by disabling or deleting an API key, instantly preventing further authentication.
• Performance: API keys are typically smaller in size than JWT tokens, resulting in reduced bandwidth consumption.

Disadvantages

• Key Management: Managing and securing a large number of API keys can be challenging, requiring robust key rotation and storage practices.
• Insecure Transmission: API keys sent in plain text via URLs or headers may be vulnerable to interception, necessitating additional security measures like HTTPS and sender/receiver environment security controls.

Usage

In the settings of the workspace API key, enable Basic access authentication.

In the following examples, these values are used:

• Workspace GUID (login): a919b437-c958-46a5-a82e-b1b2d9b68f61
• API key (password): 065e6fe6-8515-44b3-8427-d8a764295ba2

1. Encode the workspaceGuid:apiKey combination with base64.
   Example:
   JavaPython

   import java.nio.charset.StandardCharsets;
   import java.util.Base64;
   
   class Scratch {
       public static void main(String[] args) {
           System.out.println(new String(Base64.getEncoder().encode("a919b437-c958-46a5-a82e-b1b2d9b68f61:065e6fe6-8515-44b3-8427-d8a764295ba2".getBytes(StandardCharsets.UTF_8))));
       }
   }
   

   import base64
   
   loginAndPassword = b'a919b437-c958-46a5-a82e-b1b2d9b68f61:065e6fe6-8515-44b3-8427-d8a764295ba2'
   print(base64.b64encode(loginAndPassword).decode('utf-8'))
   

   Result:

   YTkxOWI0MzctYzk1OC00NmE1LWE4MmUtYjFiMmQ5YjY4ZjYxOjA2NWU2ZmU2LTg1MTUtNDRiMy04NDI3LWQ4YTc2NDI5NWJhMg==
   

2. Include the result (preceded by "Basic") in the Authorization header of the request:
   

   curl --location 'https://api.synerise.com/v4/events/custom' \
   --header 'Authorization: Basic YTkxOWI0MzctYzk1OC00NmE1LWE4MmUtYjFiMmQ5YjY4ZjYxOjA2NWU2ZmU2LTg1MTUtNDRiMy04NDI3LWQ4YTc2NDI5NWJhMg==' \
   --header 'Api-Version: 4.4' \
   --header 'Content-Type: application/json' \
   --data '{
       "action": "auth.test",
       "client": {
           "id": 6501571767
       },
       "params": {
           "test": true
       },
       "label": "string"
   }'