API Endpoints

Mapping Seat IDs

In a production environment, an SSP's seat IDs are sent to LiveRamp for mapping. A seat ID is the partner-specific identifier that tells Sidecar which demand endpoint a decrypted ID should be mapped to. This is typically the seat or account ID your DSP or downstream SSP already uses in the exchange.

To add new mapping or change existing seat IDs, contact [email protected]. You can provide your mappings in the following format:
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 supports an endpoint under /v2/map that allows for decryption of a single envelope to multiple available ID Sources.

It accepts three parameters:

A required env=[envelope_ID] parameter
An optional sid=[seat_ID] parameter that can refer to a single seat, or repeat for multiple seats
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 included, 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 labeled 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 that Sidecar becomes unauthorized. There is no need to query the /health endpoint prior to each request.

HTTP Status Code	Meaning	Remediation
`200`	Successful lookup	N/A
`204`	The envelope-contained data is not authorized for certain partners.	N/A
`400`	Bad request
`401`	Unauthorized
`404`	Not found	URL path is not supported. Verify URL
`405`	Method not allowed	Update method
`410`	The envelope has expired.	Check your envelope source and reduce any caching (or request the same from the publisher).
`412`	Sidecar does not have access to the envelope decryption key the publisher used.	Publisher/partner may not be base64 decoding the stored envelope. Request that they base64 decode the stored envelope before passing in the bidstream. Request that the publisher enable your access or stop sending you Envelopes.
`500`	Something unexpected goes wrong within Sidecar.	Document requests that cause this behavior and report them to LiveRamp. Sidecar will report telemetry on failures back to LiveRamp for production Sidecar builds.

Checking Sidecar Status - `/health`

Use the health check endpoint to check Sidecar status without running through envelopes. It takes no arguments and returns a JSON response, along with a transparent HTTP status code to indicate Sidecar 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 Sidecar is authorized and ready to accept and map requests.
503 (Service Unavailable) indicates that Sidecar has started, but has not yet successfully completed its initial authorization routine. Under normal operation, Sidecar shouldn't stay in this state for an extended period of time. Seeing this code for an extended period could indicate that Sidecar is unable to reach LiveRamp servers. If this happens, contact your LiveRamp representative.
401 (Unauthorized) indicates that Sidecar contacted LiveRamp, but LiveRamp denied the request for keys. Sidecar may go into this state 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 reauthorized Sidecar.
keys_ttl is a Unix timestamp in seconds of when the current authorization will expire. It is 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 that 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.

A /config response contains the following data:

Sidecar version
Instance ID
ID sources
Supported Seat IDs (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

Example:

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%"

Mapping Seat IDs

Retrieving Identifiers - /v2/map

🚧The v1 /map endpoint will be deprecated in early 2023

Checking Sidecar Status - /health

Monitoring Sidecar - /metrics

Sidecar Metadata - /config

Error Logging

Retrieving Identifiers - `/v2/map`

🚧
The v1 /map endpoint will be deprecated in early 2023

Checking Sidecar Status - `/health`

Monitoring Sidecar - `/metrics`

Sidecar Metadata - `/config`