API Session Key Refresh

[jcoomans]

OK. . .I am building a custom app and I am having difficulty with the connection. The API is simple, and it uses an API key to generate a session key for all subsequent requests.

However, there is no expiration information on the session key that is generated. So, I created my own expiration, but the connection is NOT renewing the key. I have to manually click on Verify in the connection to fix it.

Here’s my Connection code:
{
// ****************************
// * API REQUEST *
// ****************************

// URL for the API request, dynamically set based on environment parameters.
"url": "https://{{parameters.environment}}.qliqsoft.com/quincy_api/v1/session", 

// HTTP method used for the request.
"method": "POST",

// ****************************
// *       HEADERS            *
// ****************************

"headers": {                                   
    // Authorization header with API key for authentication.
    "Authorization": "{{parameters.apiKey}}"  
},

// ****************************
// *   RESPONSE HANDLING      *
// ****************************

"response": {
    "data": {
        // Stores the session key from the response for future API calls.
        "sessionKey": "{{body.session_key}}",  

        // Sets session expiration time (current time + 3600 seconds = 1 hour).
        "expires": "{{addSeconds(now, 3600)}}"  
    },

    "metadata": {                                     
        // Specifies the type of metadata (either "text" or "email") for the connection label.
        "type": "email",                               

        // Displays the authorized user's email in the connection label (not functional yet).
        "value": "{{body.user.email}}"            
    },

    "error": {                                         
        // Formats error messages as "[statusCode] error text" for debugging.
        "message": "[{{statusCode}}] {{body.error}}"  
    }
},

// ****************************
// *  SESSION REFRESH LOGIC   *
// ****************************

"refresh": {  
    // Re-authentication URL, same as initial request.
    "url": "https://{{parameters.environment}}.qliqsoft.com/quincy_api/v1/session",
    "method": "POST",

    "headers": {
        // Authorization using API key for refreshing the session.
        "Authorization": "{{parameters.apiKey}}"
    },

    "response": {
        "data": {
            // Refreshes session key and resets expiration time.
            "sessionKey": "{{body.session_key}}",
            "expires": "{{addSeconds(now, 3600)}}"  
        },

        "error": {
            // Handles error messages during session refresh.
            "message": "[{{statusCode}}] {{body.error}}"  
        }
    }
},

// HTTP status codes that trigger automatic session refresh.
"refreshOn": [401, 403],  

// ****************************
// *        LOGGING           *
// ****************************

"log": {
    "sanitize": [                                     
        // Excludes the "Authorization" header from logs to protect sensitive data.
        "request.headers.authorization"               
    ]
}

}

And here is my parameters code:
[
// ****************************
// * API AUTHENTICATION *
// ****************************

{
    // Description: API Key required for authentication.
    // Instructs the user where to obtain the API key.
    "help": "Your Quincy API Key acquired from the admin dashboard.",  

    // Internal name used for referencing this parameter.
    "name": "apiKey",

    // Type of input field (password field hides input for security).
    "type": "password", 

    // User-friendly label for display in the UI.
    "label": "API Key", 

    // Allows user to modify this value after initial setup.
    "editable": true,  

    // This field is mandatory for authentication.
    "required": true  
},

// ****************************
// *   ENVIRONMENT SETUP      *
// ****************************

{
    // Instructs the user which app environment to connect to (e.g., production or sandbox).
    "help": "The environment to which you will connect.",  

    // Internal name used for referencing this parameter.
    "name": "environment",

    // Type of input field (plain text).
    "type": "text",  

    // User-friendly label for display in the UI.
    "label": "Environment",  

    // This field is required for establishing a connection.
    "required": true,  

    // Allows user to modify this value after initial setup.
    "editable": true,  

    // Default environment value (e.g., "capi" as the default connection point).
    "default": "capi"  
}

]

Am I just doing something stupid? I can’t understand why the Connection is not refreshing unless I manually click on Verify.

[jcoomans]

OK, I figured it out, despite the complete lack of documentation on the subject and all the training materials.

First, either it’s a bug, or they simply fail to tell you that when you pick the API connection type, the refresh option simply won’t work, ever. The connection MUST be defined as an Oauth 2.0 (token with refresh), and then modified for it to work, despite the fact that it is NOT Oauth. So, for those of you that wanted to know, here’s how it’s done:

{
  // ****************************
  // *       API REQUEST        *
  // ****************************

  "token": {
    // 🔄 Condition to determine if the session key needs to be refreshed:
    // - If a sessionKey exists, check whether it expires in less than 1 minute.
    // - If no sessionKey is stored, always trigger the request.
    "condition": "{{if(data.sessionKey, data.expires < addMinutes(now, 1), true)}}",

    // 🌐 Endpoint to request a new session token (sessionKey).
    "url": "https://{{parameters.environment}}.qliqsoft.com/quincy_api/v1/session",
    "method": "POST",

    // ****************************
    // *         HEADERS          *
    // ****************************
    "headers": {
      // 🔐 API Key used for authentication.
      "Authorization": "{{parameters.apiKey}}"
    },

    // ****************************
    // *      TOKEN RESPONSE      *
    // ****************************
    "response": {
      "data": {
        // ✅ Store the session key from the API response.
        "sessionKey": "{{body.session_key}}",
        
        // ⏳ Define session key expiration: current time + 3600 seconds (1 hour).
        "expires": "{{addSeconds(now, 3600)}}"
      },

      // ❌ Error formatting for visibility in logs/debugging.
      "error": {
        "message": "[{{statusCode}}] {{body.error}}"
      }
    },

    // ****************************
    // *        LOGGING           *
    // ****************************
    "log": {
      "sanitize": [
        // 🚫 Exclude API key from request logs for security.
        "request.headers.authorization",

        // 🚫 Exclude session key from response logs to avoid exposure.
        "response.data.sessionKey"
      ]
    }
  }
}

Obviously, if you’ve run across the same issue, I’d love to hear from you.