Skip to main content

Migrating from API v1 to v2: Enhanced Security and Authentication

Updated

 

As we approach the sunset date for v1 of the eSPACE APIs, it’s crucial that all organizations  migrate to v2. Version 2, which has been available for a couple of years, offers substantial enhancements in security and authentication. This document outlines the key advantages of v2 and provides a guide to help you seamlessly transition your systems. By upgrading, you’ll not only ensure continued access to our API beyond the v1 sunset date, but also benefit from improved features and robust security measures.

 

V1 Usage

Integrations: It's important to know that any integration that we have built such as COOLSPACE (HVAC) and SECURESPACE (access control), do NOT use API 1. However, like many companies, we offer API's for customers to use so they can pull data from their eSPACE in raw form and use as they desire.

Why Use API Calls: The most common scenario in which our customers use our API calls is to "pull" event data from their eSPACE account to then display on their website, but there may be others. We wouldn't have any way to tell how someone is using them. It's like buying a generic product in a store and trying to predict how someone is going to use it. However, for anyone who we have identified as still actively using API version 1, we are now notifying them and encouraging them to switch to version 2.

API Key: Since API version 1 doesn't require an API key you won't be able to see who is using API version 1 by navigating to the profile icon/Profile/API key.

 

Benefits of V2

The primary difference between v1 and v2 lies in the authentication method. While v1 uses HTTP Basic Authentication, v2 implements JSON Web Tokens (JWT) for enhanced security. JWT provides a more robust security model, reducing the risk of credential interception.  Additionally, V2 offers many more endpoints, including many for our Work Order and Asset Management module.

Migration Steps

Follow these steps to upgrade your systems from v1 to v2:

1. Generate API Keys:

  • Log in to your eSPACE account.
  • Navigate to the Profile page in eSPACE and find API Keys section.
  • Create a new API Key.
  • Store the generated key securely; it won't be displayed again
  • Note that the access and permissions of the user in eSPACE will have the same access and permissions through the APIs.

2. Update Authentication Method in Your Systems Calling the eSPACE API Endpoints:

  • Replace HTTP Basic Authentication with JWT
  • Obtain a JWT token by sending a POST request to the v2/requesttoken endpoint
  • Include the following JSON payload:

      {

       "apiKey": "your_generated_api_key"

    }

3. Implement JWT Authentication:

  • Store the received JWT token securely
  • Include the JWT token in the Authorization header of all API requests:

     Authorization: Bearer <your_jwt_token>

4. Update Your API Endpoint requests:

  • Replace all v1 endpoint URLs with their v2 counterparts
  • Ensure the new JWT Token is included with all new requests (step 3 above)
  • Refer to the updated API documentation for any changes in request/response formats

5. Test Your Integration:

  • Thoroughly test all API calls using the new v2 endpoints and JWT authentication
  • Verify that your application functions correctly with the updated authentication method

6. Monitor Token Expiration:

  • Implement token refresh logic to obtain a new token when necessary
  • If you receive a 401 error, request a new JWT token
  • Each key will be valid for about a year, or whenever the authenticating user changes their email or password.

For more help:

FAQ

1. Why do we need to migrate from API v1 to v2?

   - API v1 is being sunset on April 21, 2025, and migrating to v2 ensures continued access to our services. Additionally, v2 offers enhanced security and more endpoints, including those for the eSPACE Work Order and Asset Management module.

2. What are the main differences between API v1 and v2?

   - The key difference is the authentication method: v1 uses HTTP Basic Authentication, while v2 uses JSON Web Tokens (JWT) for improved security. V2 also provides better performance and access to more endpoints, including those for the eSPACE Work Order and Asset Management module.

3. How do we transition our existing integrations to API v2?

   - Follow the migration guide provided in our documentation, which includes generating new API keys, updating authentication methods, and testing your integration with the new endpoints.

4. Will we need technical expertise to complete the migration?

   - It’s likely that you will need the same technical knowledge that was required to originally implement use of eSPACE v1 APIs. But it depends on exactly how your v1 implementation was done.

5. How do we generate API keys for v2 authentication?

   - Visit the support article for detailed instructions on creating API keys. Ensure these keys are stored securely as they are essential for accessing the API.

6. What happens if we don't migrate to API v2 before the sunset date?

   - After the sunset date, API v1 will stop responding to requests, and that will likely disrupt your integrations and access to data through the APIs.

7. How does the new JWT authentication affect our data security?

   - JWT provides a more secure authentication method by reducing the risk of credential interception and allowing stateless authentication.

8. Are there any changes to permissions and access controls in API v2?

   - Permissions are generally the same in that they are based on the authenticating user.  Access levels in v2 are determined by the eSPACE user associated with the API key. Ensure that the user has appropriate permissions for the data you wish to access or modify.  You might even consider creating a dedicated user account for the sole purpose of providing API Keys.

9. Will there be any changes in how data is read or modified through the API?

   - We attempted to make V2 requests and responses backward compatible with V1.  Once the authentication process is updated, most calls made for V1 API should behave the same way for V2. 

10. What are ways we can troubleshoot issues we encounter?

    - The eSPACE API Swagger documentation and “Try it out” tool can be found at https://api.espace.cool.  We strongly recommend you start there.  We also suggest you leverage a tool like Postman to build and test calls.

Related articles