Integrate with ConnectID: Server to Server Integration Method

Sellers wanting to integrate with ConnectID via the Server to Server integration method must follow the processes 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 is a web service that returns ConnectIDs (cookieless user identifiers) when a Seller sends us a hashed email address from a logged-in user on their site.

1 Obtain Yahoo Credentials

The ConnectID Server-to-Server API is secured by OAuth2 authentication, it requires that each request for a ConnectID contains 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 a private/public key using openssl following the process below so that Yahoo can encrypt the OAuth Secret.

Create a Private/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. Use the private key above to generate a public key.

>> 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 with an email that contains 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 and 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 your credentials.


To reset or forget your Secret, follow the instructions above to get new credentials.

Then use the credentials to generate an access token.

2 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 Yahoo ID-B2B endpoint.

Important! The body of the POST request must contain a JSON Web Token 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 token is signed (generally using HMAC SHA-256 algorithm)

2. Free set of claims for you want: client_id, aud, expiration date, etc.

3. Signature ensuring 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). You may get the "JWT is has expired or is not valid" error.

"urn:vm:claims:fedidp_tenant" is an optional value. Pass this only if a token exchange is needed using 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 A Final JWT token







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

Sample code to generate JWT and get an 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.


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 for the 10 minutes.

  1. Set the Body of the Request

Sample 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.

Sample Response

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.

3 GET Yahoo ConnectID

The ConnectID server-to-server API accepts a 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 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


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