Integrate with ConnectID: Server-to-Server Method

The Yahoo ConnectID is designed to enable ad tech platforms to recognize and match users consistently across the open web. ConnectID is built on top of the robust and proprietary Yahoo ID Graph and enables publishers to thrive in the cookieless world.

Server-to-Server method is only one of the ConnectID integration methods. It is most appropriate in the following situations:

  • When a Publisher is integrated with Yahoo SSP via several methods such as prebid, tags or S2S.

  • When a Publisher is integrating ConnectID as an identity solution for their CTV supply

Sellers integrating with ConnectID via the Server-to-Server method must follow the process outlined in this article. A seller must first obtain Yahoo credentials to generate an access token at run time in order to obtain a ConnectID. This integration method uses a web service that returns ConnectIDs (cookieless user identifiers) when a seller sends us a hashed email address.

Obtain Yahoo Credentials

The ConnectID Server-to-Server API is secured by OAuth2 authentication. Each request for a ConnectID must contain an access token derived from the Yahoo OAuth2 credentials. OAuth Credentials consist of a Client ID and Secret. An Account Manager will send the credentials securely. A Seller must create both a private and public key using Openssl following the process below so Yahoo can encrypt the OAuth Secret.

Once the “Obtain Yahoo Credentials” process below is completed, work with your Account Manager or reach out to to obtain the information necessary for the next step.

Create both a Private and Public Key using Openssl

  1. Install Openssl from a trusted source.
  2. Generate a private key using the following command line.

>> openssl genpkey -aes256 -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private_key.pem

  1. Generate a public key using the following command line and the private key generated in step 1.

>> openssl rsa -in private_key.pem -out public_key.pem -outform PEM -pubout

  1. Email the public key to the Account Manager.

An Account Manager will respond via email with a Publisher ID, OAuth client ID and a file that is encrypted with the above public key containing your account password.

  1. Decrypt the file containing your OAuth credentials with the private key by entering the following command line.

>> openssl rsautl -decrypt -inkey private_key.pem -in credential.enc -outmy_credentials.txt

Security Considerations

OAuth credentials must be protected and NEVER exposed. They should also be reset periodically. All interactions MUST be protected by Transport Layer Security (TLS). Do not embed credentials directly in code to avoid being accidentally exposed to the public. Instead, store your credentials in environment variables or in files outside of the application's source tree. If your credentials are compromised at any point, it is very important to reset them.

To reset or get a new Secret, repeat the instructions above.

Generate Yahoo Access Token

The ConnectID Server-to-Server API integration method requires an OAuth2 access token for every request. The following process details how to generate a Yahoo access token by obtaining a valid token then submitting a POST request to the ID-B2B endpoint.

Important: The body of the POST request must contain a JSON Web Token (JWT) containing the OAuth2 credentials obtained above. To obtain an access token generate a JWT first.

Note: Sample Code for Token Generation supplied on request. Please reach out to your account manager.

Generate JSON Web Token (JWT)

A JSON Web Token is composed of three main parts:

1. Header - normalized structure specifying how the token is signed (generally using HMAC SHA-256 algorithm).

2. Claims - a free set of your choice: client_id, aud, expiration date, etc.

3. Signature - to ensure data integrity.

The signature mechanism is HMAC_SHA256 as defined by the JOSE specifications (


JWT Header


"alg": "HS256",

"typ": "JWT"



JWT Claims


"aud": "",

"iss": "{client_id}",

"sub": "{client_id}",

"exp": {expiry time in seconds},

"iat": {issued time in seconds},


NOTE: "exp" and "iat" values should be numeric. Do not set them as strings.

"exp" value should be less than 24 hrs. Preferable time is currentTime + 600 (ie 10 minutes). Do not use currentTime + (24 * 60 * 60) as this may produce the "JWT is has expired or is not valid" error.

"urn:vm:claims:fedidp_tenant" is an optional value. Pass this only if exchanging a federated token.


JWT Signature

jwt_signing_string = base64url_encode(jwt_header) + '.' + base64url_encode(jwt_body);

jwt_signature = base64url_encode(hmac_sha256(jwt_signing_string, client_secret))

JWS = jwt_signing_string + '.' + jwt_signature


Manual steps to build the JWT value

jwt_header = '{"typ":"JWT","alg":"HS256"}';

jwt_body = '{






jwt_signing_string = base64url_encode(jwt_header) + '.' +


jwt_signature = base64url_encode(hmac_sha256(jwt_signing_string,


JWS = jwt_signing_string + '.' + jwt_signature


Example of the final JWT token







<base64url-encoded header>.<base64url-encoded claims>.<base64url-encoded signature> (They are separated by a “.”)


Sample code blocks for generating a JWT and access token are provided below.

Request An Access Token

Request an access token from the ID-B2B endpoint using the JWT generated from the client ID and secret. Include the token in the requests to our ConnectID S2S endpoint.

Important! The token remains active for 10 minutes, and may be re-used instead of requesting a new token for every postback. Also, the token can be refreshed or regenerated at around 8-9 minutes instead of waiting the full 10 minutes.

  1. Set the Body of the Request


POST /identity/oauth2/access_token HTTP/1.1


Content-Type: application/x-www-form-urlencoded

Accept: application/json grant_type=client_credentials&scope=connectid&realm=ups&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc 3MiOiJkNjI0YmI4My03MzViLTRmNTMtYjU1Ni03YTEzMGM5YzAxZjMiLCJzdWIiOiJkNjI0YmI4My03Mz ViLTRmNTMtYjU1Ni03YTEzMGM5YzAxZjMiLCJhdWQiOiJodHRwczovL2lkLXVhdDIuY29ycC5hb2wuY 29tL2lkZW50aXR5L29hdXRoMi9hY2Nlc3NfdG9rZW4_cmVhbG09YjJiIiwiaWF0IjoxNDc1MDk1Mjg1Ljk 1NCwiZXhwIjoxNDc1MDk1NTg1Ljk1NCwicmVhbG0iOiJiMmIifQ.JzeW4YvrN7HC1nAcrj21_9yn2i3Iq9b abpTmbNuPfcM


Required Body Request Fields

Field Name





MUST be 'client_credentials'



MUST be 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'



JWS value (varies for each client request)



MUST be ‘connectId’



MUST be ‘ups’

  1. Submit a POST Request to

Note: Make sure the Content-Type is set to application/x-www-form-urlencoded.


Format: json Status: 200 Headers: Content-Type: application/json


"access_token": "0bed77b1-435e-4b51-9ff0-f087a75941de",

"scope": "connectId",

"token_type": "Bearer",

"expires_in": 599



If errors occur while obtaining the access token, see the Access Token Troubleshooting document or reach out to an Account Manager.

GET Yahoo ConnectID

The ConnectID server-to-server API accepts an HTTPS GET request with a hashed user email and the Publisher ID as parameters and returns a JSON object containing the ConnectID associated with the hashed email.

GET Request

Put the access token in the request header to invoke the Yahoo ConnectID Server-to-Server API. The header name is Authorization and the value is the access token.


curl '

ea7e63030cf1cb5b2b3c14bfdae00e3exxxxxx&pi=1001' --header 'Authorization: Bearer






Query Parameters

Parameter Name







Hashed version of the user’s email address




Publisher ID, supplied by your account manager during onboarding.




=0 if the user is NOT subject to GDPR rules

=1 if the user is subject to GDPR rules




IAB TCF2.0 consent string, if gdpr=1

ipaddr String optional End-user's IP address is used to determine their location
us_privacy String optional IAB CCPA/us-privacy, end-user's CCPA selections. Applied to users from all US states as determined by the IP parameter.
gpp String optional IAB GPP consent string.
gpp_sid String optional IAB GPP applicable section ID, comma-separated list of integers .
ipaddr String


ipaddr String optional IP address of the end user. Used for optional geo-blocking by specified country.
att String optional Apple App Tracking Transparency 1-char code
ifa String optional Identifier for Advertising, use this identifier in ad requests.
app String

required if ifa is present

Name of the app.


Request Header

Header Name





Bearer <access token> Where access token is the token received from the ID-B2B endpoint


GET Response

The ConnectID Server-to-Server API will respond with a 200 OK and a Content-Type Header value of “application/json”. A JSON object in the body of the response contains one field consisting of 2 strings, the name of the field and the ConnectID value.



"connectId": "P8XXUtgxNktZDDRg0FSPZXanjlpNCyRsMeZBr9pK_N6UwNkzCpbIeDQa3vx8Ekqv6KhRlhli5xN-TP0hZufwLw"



HTTP Status Return Codes

Status Code





The response contains a JSON object

Important! If gdpr=1 was specified on the request and the gdpr_consent is not present or does not have Yahoo consent enabled, the response will be 200 OK with an empty JSON response.


Bad Request

Missing required parameters



The access token does not grant access to ConnectID S2S API

403 Forbidden The app parameter value in the ConnectID request is from an unauthorized app


Include ConnectID in Ad Requests

For sellers using Prebid, follow the example below to include ConnectID in ad requests. Refer to additional documentation.


userSync: {

userIds: [{

name: "connectId",

storage: {

type: "html5",

name: "connectId",

expires: 1


value: {

connectId: "example-value"





For CTV sellers, ConnectID does not need to be passed in the ad request. Instead, a match table is established using the server-to-server integration method between the IFAs (Identifier for Advertising) and ConnectIDs derived from hashed emails passed via this integration. This match table is used by Yahoo to look up the ConnectID corresponding to the IFA passed in the ad request. Thus, it is crucial to ensure that the IFA passed via the server-to-server ConnectID integration method is the same as the one passed in the ad request.

Honoring Privacy Choices

Yahoo ConnectID provides multiple mechanisms for users to manage their privacy choices. Users can manage their choices via the ConnectID Control Portal, on the Yahoo Privacy Dashboard and NAI’s Audience Matched Opt Out page. Additionally, Connect ID also respects industry-standard privacy signals (e.g., CCPA Do Not Sell), when passed through the applicable API endpoints.

Once users are opted-out, no further actions are required by sellers as Yahoo ensures that privacy choices selected by users via any one of these methods are honored. We automatically stop generating ConnectIDs for users who have opted-out.