API Endpoints

Mapping Seat IDs

In a production environment, Seat IDs will be provided by the SSP and mapped by LiveRamp. To add new mapping or change existing seat IDs, contact [email protected]. You can provide your mappings in a simple format of:
Plaintext Name, Preferred Seat Name
A DSP's Name, 001

Retrieving Identifiers - /v2/map

🚧

The v1 /map endpoint will be deprecated in early 2023

For new features and ongoing support, please migrate to the latest Sidecar version.

v2/map

Sidecar v2 introduces a new endpoint, presented under /v2/map, that allows for decryption of a single Envelope to multiple available IDSources.

It accepts three parameters: a required “env=[Envelope identifier]” parameter an optional “sid=[seat ID]” parameter that can refer to a single seat, or repeat for multiple seats and an "idsource=[idsource string"]. The /v2/map endpoint returns a JSON array of objects containing an identifier source as well as one or more seat mappings.

$ curl -v 'localhost:5000/v2/map?env=AutVJed5qoEQ6hvuS9OharoNa8tyk1Hoa2nz8hv-50SASJb7TkzxhgeHnknLDVXvs5GGv-8V_CUdtNztqQmLvwUxIlA'
> GET /v2/map?env=AutVJed5qoEQ6hvuS9OharoNa8tyk1Hoa2nz8hv-50SASJb7TkzxhgeHnknLDVXvs5GGv-8V_CUdtNztqQmLvwUxIlA HTTP/1.1
> Host: localhost:5000
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 3528

[
  {
    "source": "liveramp.com",
    "mapping": {
      "SEAT0029": "XY0029yIz8i7-uBNtfZXdP5LFtsxjb4B82Om-ZrJh8rpo-rjU",
      "SEAT0030": "XY00301decxLOMNZn7W7MAgLlwUcU1ODM1xag_U5IFDRY_IDo"
    }
  },
  {
    "source": "uidapi.com",
    "mapping": {
      "SEAT0029": "AgAAAAPHpn5cHG8VyP6CAuHh5AMemVXXXxMdVzjhmdRl0nt8cglqmMRWTmKap05HIeNpLvEaAERX2mLp0RVSJz0M48igDHx53dsrnaenCAG/VDTJcAkHFLIplzOFjYASu0wtXsJ3IBNAWjSABjs7xmEXq73B16HRZAeCCBBKGBdvhp0rww==",
      "SEAT0030": "AgAAAAPHpn5cHG8VyP6CAuHh5AMemVXXXxMdVzjhmdRl0nt8cglqmMRWTmKap05HIeNpLvEaAERX2mLp0RVSJz0M48igDHx53dsrnaenCAG/VDTJcAkHFLIplzOFjYASu0wtXsJ3IBNAWjSABjs7xmEXq73B16HRZAeCCBBKGBdvhp0rww=="
    }
  }
]

If “sid” parameters are used, only the provided Seat IDs and associated identifiers will be included in the output. If no "sid" parameter is included, the endpoint returns identifiers for all available seats the sidecar is authorized for.

By default, any seats configured as "passthrough" (e.g. envelope output without further processing) will fall under the liveramp.com source. If you'd prefer to split out "passthrough" separately, add the parameter -separate-passthrough to your docker run command. Any eligible seats will be grouped under a new IDSource domain labelled passthrough.

{
    "source": "passthrough",
    "mapping": {
      "Seat001": "AilAgXIT4x_KFo_T_Z8rtKu0aj6BPYZBXuPVcfHN7I_wDEmHzxCdaXxodDxqH5F6wmgKaeW7d45wR40zZfMDqvfRDCUWJWChw_Ku"
    }
  }

The v2/map endpoint is intended to always return a quick response, even in the event the Sidecar becomes unauthorized. There is no need to query the /health endpoint prior to each request.

Checking Sidecar Status - /health

Use the health check endpoint to check the status of the sidecar without running through Envelopes. It takes no arguments and returns a JSON response, along with a transparent HTTP status code to indicate the sidecar’s status.

$ curl -v localhost:5000/health
*   Trying 127.0.0.1...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 5000 (#0)
> GET /health HTTP/1.1
> Host: localhost:5000
> User-Agent: curl/7.64.1
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Content-Length: 49
<
* Connection #0 to host localhost left intact
{"last_successful_authentication":0,"keys_ttl":0}* Closing connection 0

• 200 (OK) indicates that the sidecar is authorized and ready to accept /map requests.
• 503 (Service Unavailable) indicates that the sidecar has started, but has not yet successfully completed its initial authorization routine. Under normal operation, a sidecar should never stay in this state for an extended period of time. Seeing this code for an extended period could indicate that the sidecar is unable to reach LiveRamp servers. In this case, please contact LiveRamp.
• 401 (Unauthorized) indicates that the sidecar has contacted LiveRamp, but LiveRamp has denied the request for keys. A sidecar may go into this state during the course of operation if LiveRamp revokes authorization remotely, or if the container loses connectivity and the authorization times out.
• last_successful_authentication is a UNIX timestamp in seconds of the last time LiveRamp re-authorized the sidecar instance.
• keys_ttl is a UNIX timestamp in seconds of when the current authorization will expire -- it will be equivalent to the last_successful_authentication + four hours.

Monitoring Sidecar - /metrics

You can check to see how much data a sidecar instance is processing (and at what internal latency) by calling the /metrics API endpoint.

$ curl localhost:5000/metrics 
{
  "map_latency_50_percentile": 116300,
  "map_latency_90_percentile": 181400,
  "map_latency_99_percentile": 1.56745e+06,
  "query_count": 3779,
  "bad_request_count": 0,
  "expired_envelopes_count": 0,
  "no_content_count": 0,
  "map_key_handler_query_count": {
    "2": 3779
  },
  "map_not_supported_handler_count": {}
}

This will return the number of requests processed, the subset which were bad requests and latency (measured in nanoseconds) at various percentiles. As part of the v2.2 release two new metrics have been added:

• "expired envelopes" error count
• "no content" error count

Adding /prometheus will return the metrics in Prometheus metric format:

$ curl localhost:5000/metrics/prometheus
# HELP bad_request_count Number of bad requests per minute
# TYPE bad_request_count gauge
bad_request_count 0
# HELP map_key_handler_query_count Number of requests per key handler in a minute
# TYPE map_key_handler_query_count gauge
map_key_handler_query_count{key_handler="2"} 3642
# HELP map_latency_50_percentile 50th percentile latency number
# TYPE map_latency_50_percentile gauge
map_latency_50_percentile 114400
# HELP map_latency_90_percentile 90th percentile latency number
# TYPE map_latency_90_percentile gauge
map_latency_90_percentile 180800
# HELP map_latency_99_percentile 99th percentile latency number
# TYPE map_latency_99_percentile gauge
map_latency_99_percentile 937850
# HELP query_count Number of queries processed in a minute
# TYPE query_count gauge
query_count 3642

Sidecar Metadata - /config

You can check to see your sidecar instance configuration by calling the /config API endpoint.

Config response will contain the following data:

• Sidecar version
• Instance id
• ID Sources
• Supported SeatIds (per id source)

Example: 
curl -v "localhost:5000/config"

Response:
{
"sidecar_version": "test_version",
"instance_id": 1234,
"id_sources": [
	"liveramp.com",
	"test-noop-source"
],
"seat_ids_by_id_source": {
	"liveramp.com": [
		"SEAT0000",
		"SEAT0001"
	]
}
}

Error Logging

For logging errors and warnings, when the error count reaches a predefined threshold, flags -warning-threshold and -error-threshold can be used. The default value is 50 for -warning-threshold and is 90 percent for -error-threshold. Threshold values can be adjusted as required.

Candidates for these logs are:

• bad request
• no content
• expired envelope
• not supported key handle

docker run  -v /cert_folder/:/mnt/certs --cap-add IPC_LOCK -p 127.0.0.1:5000:5000 liveramp/idl-mapper:latest -listen tcp://:5000 -certificate " " -warning-threshold 60 -error-threshold 80

Example warning log for bad requests:
level=warning msg="bad_request_count rate is 75% which is equal or above the defined threshold of 60%"

Example error log for bad requests:
level=error msg="bad_request_count rate is 100% which is equal or above the defined threshold of 80%"