Custom authentication and authentication renewal (refresh)

Edit online

Use custom authentication in Connector Development Kit to define flexible, multi-step authentication flows that support complex API requirements. This feature allows connector developers to configure advanced processes for token generation and renewal (refresh) without writing custom code.

Purpose

Standard authentication types in Connector Development Kit, such as Basic, Bearer token, and API key use a fixed flow that sends credentials or tokens to a predefined server URL. This approach is sufficient for many APIs but does not support advanced authentication scenarios that require dynamic token generation, custom headers, or intermediate API calls.

Custom authentication enables developers to configure these scenarios using the Custom authentication configuration and Authentication renewal configuration tabs.

When to use custom authentication

Use custom authentication when the target API requires:
  • A token or session ID to be generated dynamically.
  • A token is to be retrieved from a separate authentication endpoint.
  • A refresh token is to be exchanged when the original token expires.
  • Custom headers, query parameters, cookie parameters, or request bodies are required during authentication.
  • Multiple HTTP steps are required to complete the authentication flow.

Features

Custom authentication supports the following features:
  • Configure an HTTP call to retrieve a token or session ID.
  • Define a separate call to refresh the token when it expires.
  • Use connection properties in headers, query parameters, cookie parameters, or request bodies.
  • Store and reuse values across up to five chained customized authentication steps.
  • Use different URLs for token and refresh steps.

Authentication renewal (refresh)

Use the Authentication renewal configuration tab to define how expired tokens are refreshed at run time. This configuration is triggered automatically when the application receives a 401 (unauthorized) response.

You can configure one or more refresh steps that:

  • Reuse the same configuration as the custom authentication step (token step).
  • Call a different endpoint to obtain a new token.
  • Use intermediate variables or connection properties to construct the request.
    Tip: You can copy an existing token step into the authentication renewal configuration (refresh) using the Copy custom authentication step button to avoid reentering the same details.

How it works at run time

  • The token that is generated by the custom authentication step is used in all runtime calls.
  • If a refresh step is configured, it is triggered automatically on a 401 response.
  • No changes are required in the runtime logic, only the token source changes.

Benefits

  • Supports real-world authentication patterns.
  • Reduces the need for custom code.
  • Improves developer productivity and onboarding speed.

Limitations

  • Does not support flows that require external libraries or SDKs.
  • Certificate-based authentication (for example, mTLS) is not supported.
  • Some advanced use cases (for example, AWS connectors) still require custom code.