🔐 getCredentials Event – REL-ID SDK API Documentation

📘 Overview

The getCredentials event is emitted by the REL-ID SDK when it needs the app to provide authentication credentials for a web server accessed via the REL-ID API-SDK service. This is typically triggered when a 401 Unauthorized or 407 Proxy Authentication Required status is encountered during API communication.

🎯 Purpose

This event serves as a request from the SDK to the app, asking for credentials (like Login ID or token) to authenticate the user for secure access to backend web services.

It acts as a blocking call — the SDK pauses execution and expects the app to respond using setCredentials().

🔁 Trigger Scenario

• SDK tries to access a protected web resource via an API
• Server returns HTTP 401 or HTTP 407
• SDK raises the getCredentials event and locks execution
• App must collect and respond with credentials via setCredentials()

📲 Expected App Behavior

1. Listen for the getCredentials event
2. Prompt the user for authentication credentials (e.g., username, password, OTP, token)
3. Call setCredentials() with the required credential to resume SDK execution

🧾 Sample Event Payload

The getCredentials event may not include a detailed payload, but the app is expected to construct the appropriate response.

🛠️ Sample App Flow

Step 1: SDK emits event

onGetCredentialsEvent(() => {
  // Prompt user for input
});

Step 2: App responds using setCredentials()

{
  "idType": 1,
  "value": "[email protected]",
  "operation": "authenticate"
}

📦 setCredentials() Payload Fields (in this context)

❗ Important Notes

• This is a synchronous event: SDK blocks further processing until setCredentials() is called
• Make sure the response is prompt and secure
• The app must not ignore this event, or the SDK will remain in a locked state

✅ Best Practices

• Pre-fill known credentials if already stored securely
• Minimize user friction by providing meaningful prompts
• Use secure input fields for passwords or tokens
• Handle setCredentials failure gracefully with retry logic

📎 This event is crucial for secure authentication flows when accessing external services via REL-ID SDK.