Short Lived Token Authentication

Nudge supports two types of authentication methods for better security: short-lived token authentication and static public key authentication. This document will explain how to use the short-lived token authentication method.

note

This feature is not enabled by default. Please reach out to the Nudge team to enable it.

Implementation flow overview

1. The user is authenticated by the frontend application.
2. The frontend will expose an API that returns a short-lived token to the client application based on the user’s authorization.
   • Your backend will call Nudge's getToken API to fetch this token.
3. Nudge SDKs provide a function that allows you to register your token API. The following sections explain how to use this function.

Get Token API

This API helps retrieve a short-lived token, which is valid for 60 minutes by default. It should be called from your backend, not directly from the frontend.

Endpoint URL: https://main-api.nudgenow.com/api/clients/jwt/token

Authorization

Key	Value
apiKey	YOUR_PRIVATE_API_KEY

note

You'll need to generate a PRIVATE_API_KEY from the Settings section in your Nudge dashboard.

Query Parameters

expiryMins (integer): Token expiry in minutes (default: 60 mins).

Response Format

{
  "token": "eyJhbGciOiJFZERTQSIsImtpZCI6IjBjNDk0NDRmLWRjMTAtNDMxYS04NDc0LWIyZTMwMjAyOTNlNiJ9.eyJpYXQiOjE3MzIwMjAyNDMsImV4cCI6MTczMjAyMjA0M30.gB6rKYtkwMe2itS5HWq4lnJyiDA55BIMkqx0cdvv5Z0FQAiYS1kcVkn_i_jgUL8r4WW-4185_ZkEbhK_aALMAQ"
}

Response Parameters

token (string): The short-lived token, which you will use in the refreshToken method on the frontend.

Frontend Setup

To handle token expiration and refreshing, you need to register a refreshToken method in your frontend. This method will be responsible for fetching a new token when needed.

Make sure this method is fully functional immediately after the user authenticates, as the token is necessary for all Nudge API calls.

note

Ensure that your refreshToken method:

1. Returns a valid short-lived token or null.
2. Retrieves the token from your backend when the SDK calls it.

This ensures that the SDK can call your refreshToken method whenever the token expires, maintaining a valid token for all Nudge API calls.

Example Implementations:

JavaScript

import axios from "axios";

async function refreshToken(): Promise<string | null> {
  const res = await axios.get("your_backend_api_end_point", {
    headers: {
      Authorization: your_token,
    },
  });

  if (res.statusCode === 200) return res.data.token;
  return null;
}

Java

import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

public class TokenRefresher {
    private static final OkHttpClient client = new OkHttpClient();

    public static String refreshToken() throws IOException {
        String url = "your_backend_api_end_point";

        Request request = new Request.Builder()
                .url(url)
                .addHeader("Authorization", "your_token")
                .get()
                .build();

        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful() && response.body() != null) {
                // Assuming the token is part of the response body as a JSON field "token"
                // If needed, parse the response as JSON
                return response.body().string(); // Replace with JSON parsing if necessary
            }
        }
        return null;
    }
}

Kotlin

import okhttp3.OkHttpClient
import okhttp3.Request

suspend fun refreshToken(): String? {
    val client = OkHttpClient()
    val url = "your_backend_api_end_point"

    val request = Request.Builder()
        .url(url)
        .addHeader("Authorization", "your_token")
        .get()
        .build()

    client.newCall(request).execute().use { response ->
        return if (response.isSuccessful) {
            response.body?.string()
        } else {
            null
        }
    }
}

Dart

import 'package:http/http.dart' as http;

Future<String?> refreshToken() async {
  final uri = Uri.parse('your_backend_api_end_point');

  final headers = {
    'Authorization': 'your_token',
  };

  final response = await http.get(uri, headers: headers);

  if (response.statusCode == 200) {
    // Assuming response body contains the token as plain text
    return response.body;
  }
  return null;
}

Registering your refreshToken method in Nudge SDKs

Once you've set up the refreshToken function, you need to register it with the Nudge SDK to handle token expiration.

Javascript

Nudge.registerRefreshToken(refreshToken);

Kotlin

NudgeTokenManager.registerRefreshToken{refreshToken()}

Swift

NudgeTokenManager.shared.registerRefreshToken{refreshToken()}

Key Points

1. Use the getToken API from your backend to retrieve short-lived tokens.
2. Register the refreshToken method in the Nudge SDK to manage token expiration.
3. Ensure your refreshToken method is operational immediately after user authentication.