Authentication methods

Authentication methods

This page describes the methods you need to implement in your plugin to handle destination authentication. The SDK routes all authentication-related HTTP calls to these methods automatically.

SDK requirement: @mediarithmics/plugins-nodejs-sdk v0.40.0 or later. The onTestAuthentication invalid_credentials status requires v0.40.2 or later. The feedDestinationCredentials argument on instanceContextBuilder requires v0.41.0 or later.

Methods per authentication type

Method	OAUTH2	TOKEN	LOGIN_PASSWORD	NO_AUTH
onCreateOAuthRedirectUrl	Required	-	-	-
onAuthentication	Required	Required	Required	-
onTestAuthentication	Required	Required	Required	-
onLogout	Required	Optional	Optional	-

onCreateOAuthRedirectUrl

Called when the platform needs to generate the OAuth2 authorization URL. The frontend redirects the user to this URL so they can grant access on the partner platform.

protected onCreateOAuthRedirectUrl(
  request: CreateOAuthRedirectUrlRequest
): Promise<CreateOAuthRedirectUrlPluginResponse>

Input: CreateOAuthRedirectUrlRequest

Field	Type	Description
feed_destination_id	string	The ID of the destination, created as a draft before the OAuth flow starts. Must be embedded in the state parameter of the authorization URL.
datamart_id	string	The datamart ID for the current context.
plugin_version_id	string	The plugin version ID.

Return: CreateOAuthRedirectUrlPluginResponse

Field	Type	Description
login_url	string	The full OAuth2 authorization URL. Must include a state parameter containing feed_destination_id.

Important: This method throws by default if not overridden (the SDK returns HTTP 400 not_implemented). Always override it when auth_type = OAUTH2.

Important: The redirect_uri must point to the mediarithmics Navigator callback URL: https://www.navigator.mediarithmics.com/auth/{plugin_id}/{plugin_version_id}?state={state}. The state must contain feed_destination_id so the platform can look up the destination on the OAuth callback.

Code example

protected onCreateOAuthRedirectUrl(
  request: core.CreateOAuthRedirectUrlRequest,
): Promise<core.CreateOAuthRedirectUrlPluginResponse> {
  const state = request.feed_destination_id;
  const loginUrl =
    `https://accounts.partner.com/oauth2/authorize` +
    `?client_id=${MY_CLIENT_ID}` +
    `&state=${state}` +
    `&redirect_uri=${MY_REDIRECT_URI}` +
    `&response_type=code` +
    `&scope=ads_management`;

  return Promise.resolve({ login_url: loginUrl });
}

onAuthentication

Called after the user completes the authentication step:

• For OAuth2: after the partner redirects back with the authorization code.

• For Token / Login/Password: after the user submits the form fields.

The plugin must validate the provided credentials. When feed_destination_id is present in the request, it must also return them in the response: the SDK will automatically store them in the vault via upsertFeedDestinationCredentials.

protected onAuthentication(
  request: ExternalSegmentAuthenticationRequest
): Promise<ExternalSegmentAuthenticationResponse>

Input: ExternalSegmentAuthenticationRequest

Field	Type	Description
feed_destination_id	string (optional)	Present in the new destination flow. When set, the SDK automatically upserts the credentials returned by this method into the vault.
params	Record<string, unknown> (optional)	For OAuth2: contains the redirected URL with the authorization code. For Token/Login-Password: contains the form field values.
datamart_id	string	The datamart ID.
plugin_version_id	string	The plugin version ID.
user_id	string	The user who triggered the authentication.

Return: ExternalSegmentAuthenticationResponse

Field	Type	Description
status	'ok' | 'error'	Result of the authentication attempt.
credentials	FeedDestinationCredentials (optional)	Required when feed_destination_id is present. The credentials to be stored in the vault.
message	string (optional)	Human-readable error message when status is 'error'.

FeedDestinationCredentials structure

interface FeedDestinationCredentials {
  scheme: 'OAUTH2' | 'TOKEN' | 'LOGIN_PASSWORD';
  credentials: Record<string, unknown>;
  // e.g. { refresh_token: '...' }        for OAUTH2
  // e.g. { api_token: '...' }            for TOKEN
  // e.g. { login: '...', password: '...' } for LOGIN_PASSWORD
}

Code example - OAuth2

protected async onAuthentication(
  request: core.ExternalSegmentAuthenticationRequest,
): Promise<core.ExternalSegmentAuthenticationResponse> {
  const { code } = request.params as { code: string };

  // Exchange the authorization code for tokens
  const { refreshToken } = await this.partnerClient.exchangeCodeForTokens(code);

  // Return credentials - the SDK stores them in the vault automatically
  return {
    status: 'ok',
    credentials: {
      scheme: 'OAUTH2',
      credentials: { refresh_token: refreshToken },
    },
  };
}

Code example - Token

protected async onAuthentication(
  request: core.ExternalSegmentAuthenticationRequest,
): Promise<core.ExternalSegmentAuthenticationResponse> {
  const { api_token } = request.params as { api_token: string };

  // Validate the token against the partner API before storing it
  const isValid = await this.partnerClient.validateToken(api_token);
  if (!isValid) {
    return { status: 'error', message: 'Invalid API token' };
  }

  return {
    status: 'ok',
    credentials: {
      scheme: 'TOKEN',
      credentials: { api_token },
    },
  };
}

onTestAuthentication

Called by the platform immediately after onAuthentication succeeds, and then periodically by a background job to keep destination statuses up to date. The SDK automatically fetches the credentials from the vault and passes them as the second argument.

protected onTestAuthentication(
  request: TestAuthenticationRequest,
  credentials: FeedDestinationCredentials
): Promise<TestAuthenticationPluginResponse>

Input: TestAuthenticationRequest

Field	Type	Description
feed_destination_id	string	The destination whose credentials are being tested.
datamart_id	string	The datamart ID.
plugin_version_id	string	The plugin version ID.

Input: credentials

The FeedDestinationCredentials object fetched automatically by the SDK from the vault using feed_destination_id. This is the object stored during onAuthentication.

Return: TestAuthenticationPluginResponse

status	HTTP code	When to use
'ok'	200	Credentials are valid. Destination status is set to Ready.
'invalid_credentials'	401	The partner explicitly rejected the credentials (e.g. token revoked). Destination status is set to Connection Error. Use this to distinguish credential rejection from operational failures.
'error'	500	Unexpected or operational error (network failure, partner API down).
'not_implemented'	400	Method not overridden. Default SDK behavior.

All statuses except 'ok' can include an optional message string for additional context.

Code example

protected async onTestAuthentication(
  request: core.TestAuthenticationRequest,
  credentials: core.FeedDestinationCredentials,
): Promise<core.TestAuthenticationPluginResponse> {
  if (!credentials?.credentials?.refresh_token) {
    return { status: 'error', message: 'No refresh token found in vault' };
  }

  try {
    await this.partnerClient.validateRefreshToken(
      credentials.credentials.refresh_token as string
    );
    return { status: 'ok' };
  } catch (e) {
    if (e.isUnauthorized) {
      // The partner rejected the credentials - distinct from an operational error
      return {
        status: 'invalid_credentials',
        message: 'Refresh token has been revoked or expired',
      };
    }
    return { status: 'error', message: `Unexpected error: ${e.message}` };
  }
}

onLogout

Called when the user removes the authentication from a destination. The plugin should revoke the token at the partner's end and clean up any stored state.

protected onLogout(
  request: ExternalSegmentLogoutRequest
): Promise<ExternalSegmentLogoutResponse>

Input: ExternalSegmentLogoutRequest

Field	Type	Description
feed_destination_id	string (optional)	The destination being logged out.
datamart_id	string	The datamart ID.
plugin_version_id	string	The plugin version ID.
user_id	string	The user triggering the logout.

Return: ExternalSegmentLogoutResponse

Field	Type	Description
status	'ok' | 'error'	Result of the logout operation.
message	string (optional)	Error message when status is 'error'.

Code example

protected async onLogout(
  request: core.ExternalSegmentLogoutRequest,
): Promise<core.ExternalSegmentLogoutResponse> {
  if (request.feed_destination_id) {
    const credentials = await this.fetchFeedDestinationCredentials(
      request.feed_destination_id
    );
    await this.partnerClient.revokeToken(
      credentials.credentials.refresh_token as string
    );
  }
  return { status: 'ok' };
}

SDK helper methods

The base plugin class exposes the following helpers for credential management. You can call them from any method in your plugin.

fetchFeedDestinationCredentials

Fetches the credentials stored in the vault for a given destination. Throws a ResourceNotFoundError if no credentials exist.

protected async fetchFeedDestinationCredentials(
  feedDestinationId: string
): Promise<FeedDestinationCredentials>

fetchFeedDestinationCredentialsOptional

Same as above, but returns undefined instead of throwing when no credentials are found. Useful to implement a fallback on legacy credential files during migration.

protected async fetchFeedDestinationCredentialsOptional(
  feedDestinationId: string
): Promise<FeedDestinationCredentials | undefined>

upsertFeedDestinationCredentials

Creates or updates credentials in the vault for a given destination. In the standard flow, the SDK calls this automatically from onAuthentication. Call it manually only when managing credentials outside the authentication flow.

protected async upsertFeedDestinationCredentials(
  feedDestinationId: string,
  credentials: FeedDestinationCredentials
): Promise<void>

Note on instanceContextBuilder

Since SDK v0.41.0, when a request carries a feed_destination_id, the SDK fetches the destination credentials from the vault and passes them as an optional second argument to instanceContextBuilder. Use them to initialize your partner client instead of reading from a credential file:

protected async instanceContextBuilder(
  feedId: string,
  feedDestinationCredentials?: core.FeedDestinationCredentials,
): Promise<InstanceContext> {
  const ctx = await super.instanceContextBuilder(feedId, feedDestinationCredentials);

  // Use vault credentials when available, fall back to legacy credential file
  const refreshToken =
    (feedDestinationCredentials?.credentials?.refresh_token as string) ??
    (await this.fetchLegacyRefreshToken(ctx));

  const partnerClient = new PartnerClient({ refreshToken });

  return { ...ctx, partnerClient };
}

The same credentials are also passed to onUserSegmentUpdate, onTroubleshoot, and onDynamicPropertyValuesQuery.