Authentication

Base URL

https://tv-staging.trustingsocial.com
https://vn-vision.trustingsocial.com

Access Key Authentication (Server-side)

Used by: POST /v1/register_device, POST /v1/behavior/score

These endpoints use the standard TrustVision Access Key authentication. Each request must include:

HeaderRequiredDescription
AuthorizationRequiredTV <access_key_id>:<signature>
X-TV-TimestampRequiredCurrent timestamp in RFC 3339 format (e.g. 2024-01-15T10:30:00Z)
X-TV-Content-MD5OptionalBase64-encoded MD5 hash of the request body (POST requests with encryption)

Signature computation:

string_to_sign = HTTP_METHOD + "\n" + URI + "\n" + X-TV-Timestamp + "\n" + Content-MD5
signature = HMAC-SHA256(secret_key, string_to_sign)

Customer User Device Authentication (SDK)

Used by: POST /v1/behavior/create_challenge, POST /v1/behavior/push_event_batch

These endpoints use device-level RSA authentication. Each request must include:

HeaderRequiredDescription
AuthorizationRequiredTV <customer_user_device_id>:<encrypted_secret_key>:<signature>
X-TV-TimestampRequiredCurrent timestamp in RFC 3339 format
X-Challenge-IDOptionalChallenge ID prefixed with TV , e.g. TV <challenge_id> (required for push_event_batch)

Signature computation:

string_to_sign = HTTP_METHOD + "\n" + URI + "\n" + X-TV-Timestamp + "\n" + encrypted_secret_key + "\n" + Content-MD5
signature = RSA-PSS-SHA256(device_private_key, string_to_sign)
  • encrypted_secret_key: A random AES secret key encrypted with the server's RSA public key using RSA-OAEP-SHA256.
  • signature: RSA-PSS-SHA256 signature using the device's private key.

End-to-End Encryption (SDK endpoints)

The two SDK endpoints (/v1/behavior/create_challenge, /v1/behavior/push_event_batch) use E2E encryption (the server-side /v1/behavior/score endpoint uses plain JSON with Access Key authentication — no E2E encryption):

  • Request body is encrypted with AES-GCM using the secret key from the Authorization header.
  • Response body is encrypted with AES-GCM. The response key is encrypted with the device's RSA public key using RSA-OAEP-SHA256, and the response is signed with the server's RSA private key using RSA-PSS-SHA256.

Encrypted response format:

JSON
{
  "data": "<AES-GCM encrypted response>",
  "response_key": "<RSA-OAEP encrypted AES key>",
  "signature": "<RSA-PSS-SHA256 signature of response_key + data>"
}