Identity ID

The identityId is an internal session identifier automatically generated by BizKitHub when a user logs in. Your application must store this identifier in cookies and include it in all subsequent API requests to maintain the user's authenticated session.

How It Works

The identityId flow is simple and automatic. Follow these steps to implement session management in your application.

1. User login — user authenticates via the BizKitHub API login endpoint.
2. Session creation — BizKitHub automatically generates a unique identityId.
3. Store in cookies — your application stores identityId in browser cookies.
4. API integration — include identityId in subsequent API requests.

Identity ID Characteristics

• Secure — cryptographically generated session identifier.
• Time-limited — sessions expire after a period of inactivity.
• Server-managed — automatically created and validated by BizKitHub.
• Refreshable — can be renewed through re-authentication.

Example identity ID

Z9CPkS2o3UV163VQn5OUv0T8BQi8Fvdg

• Format: 32-character alphanumeric string.
• Generated automatically during the login process.

Implementation

Step 1: Receive identityId on login

// Login request
const response = await fetch('https://api.bizkithub.com/api/v1/contact/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
apiKey: 'YOUR_API_KEY',
email: 'user@example.com',
password: 'userPassword123'
})
});
const data = await response.json();
// Extract identityId from response
const identityId = data.identityId; // e.g., "Z9CPkS2o3UV163VQn5OUv0T8BQi8Fvdg"

Step 2: Store in cookies

// Store identityId in cookies
document.cookie = `identityId=${identityId}; path=/; max-age=86400; secure; samesite=strict`;
// Or using a cookie library (recommended)
import Cookies from 'js-cookie';
Cookies.set('identityId', identityId, {
expires: 1, // 1 day
secure: true,
sameSite: 'strict'
});

Step 3: Include in API requests

// Get identityId from cookies
const identityId = Cookies.get('identityId');
// Include in API request
const response = await fetch('https://api.bizkithub.com/api/v1/contact/profile', {
method: 'GET',
headers: {
'Content-Type': 'application/json'
}
}).then(res => res.json());
// Or in request body
const response = await fetch('https://api.bizkithub.com/api/v1/contact/update', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
apiKey: 'YOUR_API_KEY',
identityId: identityId,
// ... other data
})
});

Step 4: Handle session expiration

// Check for session expiration errors
const response = await fetch('https://api.bizkithub.com/api/v1/contact/profile', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
apiKey: 'YOUR_API_KEY',
identityId: Cookies.get('identityId')
})
});
const data = await response.json();
if (data.error === 'SESSION_EXPIRED' || data.error === 'INVALID_IDENTITY') {
// Clear expired session
Cookies.remove('identityId');
// Redirect to login
window.location.href = '/login';
}

Best Practices

• Store identityId securely in HTTP-only cookies when possible.
• Never expose identityId in client-side logs or error messages.
• Clear identityId from cookies on user logout.
• Implement session timeout on the client side.
• Handle session expiration gracefully with a re-authentication flow.
• Use HTTPS for all requests containing identityId.

Common Mistakes

• Storing identityId in localStorage instead of cookies.
• Including identityId in URL parameters.
• Not clearing session data on logout.
• Caching API responses that contain user-specific data.
• Ignoring session expiration errors.

Using identityId in Swagger Documentation

In the Swagger documentation, the identityId parameter is described as:

• Parameter: identityId
• Type: String
• Description: Logged user identity (from your frontend cookies)
• Example: Z9CPkS2o3UV163VQn5OUv0T8BQi8Fvdg

See the full API documentation for the complete reference.