Skip to main content

Important: Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made by EU/UK sellers. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signature to be included in the HTTP payload.

Due to regulatory requirements applicable to our EU/UK sellers, for certain APIs, developers need to add digital signatures to the respective HTTP call. This document specifies how these signatures are created and added to HTTP payloads.

APIs in scope

Signatures are required when the call is made for EU- or UK-domiciled sellers, and only for the following APIs/methods:

Please note that signatures may be added for other APIs and/or for other sellers. eBay's system will ignore the signatures, but the API call will be accepted and handled in an ordinary manner.

Creating a payload signature

eBay's signature implementation is compliant with upcoming IETF standards (currently not yet RFCs):

NOTE: It is strongly recommended that the above drafts be reviewed.

The following HTTP headers are added to each HTTP payload for in-scope APIs called on behalf of EU/UK domiciled sellers:

eBay's Key Management API generates encrypted keypairs that are used to create the x-ebay-signature-key and the Signature headers.

The steps required to create each of the above four HTTP headers are listed below.

1. Create the x-ebay-signature-key header

The x-ebay-signature-key header always contains JWE.

Using the Key Management API, developers create the following keypairs:

  • Private Key
  • Public Key
  • Public Key as JWE

Important! In order to further ensure the security of confidential client information, eBay does not store Private Key values in any system. If a developer loses their Private Key they must generate new keypairs using the Key Management API.

The value of the x-ebay-signature-key header is the Public Key as JWE value that has been created by the Key Management API.

For example:

x-ebay-signature-key: eyJ6aXAiOiJERUYiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoiTjZIc2ItenlIXzZ4blFHQUhOdHByZyIsImFsZyI6IkEyNTZHQ01LVyIsIml2IjoiNjQ1Z0Rzc2lOYUZFb2pOWCJ9.rSWQSIKGgu_gAhLdG87fIpRYyI57KMQKYJpgQoXhPso.jvrOE0g2Q7A8h_Rj.uZsaA0VaVjL9HiciAilnNsos7Da-Fx5W3tr9sZO4qSPD-hB9t-lacy96lyeLiixs0nHXZ21iEwFYkqOllxpqW6eyJPb6lLDrnzg8Nx5AvizLagSDT35_3xBTu6EWf6x-lWBMKiBj8zo31wdjaGWMExcaQSPpwZxbJ3Z1sM4aZmHX7sjjnIT0V9kH1kAj0kD7uGuJ8KlMvrl011z68kJt-ilYG4FZn_Z5.CZzMDhEn1jqL45bYvbO3ig

2. Create the Content-Digest header

NOTE: When no HTTP payload is included (e.g., for a GET call,) this header is not required.

When an HTTP payload is included, this header provides an SHA-256 digest over the HTTP payload.

To add the Content-Digest header, calculate an SHA-256 digest over the HTTP payload (in UTF-8 character encoding). While the specification allows adding more than one digest (e.g., both SHA-256 and SHA-512,) only the SHA-256 is needed in our case.

For complete information about how to add the Content-Digest header, refer to Section 2, The Content-Digest Field, of IETF draft-ietf-httpbis-digest-headers-10.

To review an example of adding a Content-Digest header, refer to Section B.1. Server Returns Full Representation Data, of IETF draft-ietf-httpbis-digest-headers-10.

Consider the following payload:

{"hello": "world"}

In this case, the value of the Content-Digest header will be:

sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:

3. Create the signature base

The signature base is a US-ASCII string containing standard HTTP message components covered by the signature. To create the signature base, the signer or verifier concatenates together entries for each component identifier in the signature's covered components (including their parameters).

For complete information, including the detailed algorithm to create the signature base, refer to Section 2.5, Creating the Signature Base, of IETF draft-ietf-httpbis-message-signatures-15.

4. Create the Signature header

The Signature header is created using the Private Key value generated by the Key Management API (x-ebay-signature-key header) and the signature base.

The value of the Signature header is created as described in Section 3.1, Creating a Signature, of IETF draft-ietf-httpbis-message-signatures-15.

Depending on the cipher that is to be used, refer to the following specific sections of IETF draft-ietf-httpbis-message-signatures-15 for complete information:

To review examples illustrating how signature headers are created, refer to Appendix B, Examples, of IETF draft-ietf-httpbis-message-signatures-15.

Important! In order to further ensure the security of confidential client information, eBay does not store Private Key values in any system. If a developer loses their Private Key they must generate new keypairs using the Key Management API.

5: Create the Signature-Input header

This header indicates which headers and pseudo-headers are included, as well as the order in which they are used when calculating the signature.

For complete information about creating the Signature-Input header refer to Section 4, Including a message Signature in a Message, of IETF draft-ietf-httpbis-message-signatures-15.

The value of the Signature-Input header is:

sig1=("content-digest" "x-ebay-signature-key" "@method" "@path" "@authority");created=1658440308

NOTE: The value assigned to the parameter created is the Unix timestamp when the signature is first created.

If no HTTP payload is included, the header would be:

sig1=("x-ebay-signature-key" "@method" "@path" "@authority");created=1658440308

Signature validation

In both the Sandbox and Production environments, the following HTTP header is required and must be included with each in-scope API call to enable digital signature validation:

x-ebay-enforce-signature: true

Important! The header name (i.e., x-ebay-enforce-signature,) and its value (i.e., true,) are both case-sensitive. They must be lower-case.

How to test the signature

The Sandbox environment can be used to test the signature mechanism. Call the Key Management API in the Sandbox to create the Private Key, Public Key. and Public Key as JWE for testing a signature in the Sandbox.

NOTE: If preferred, open source sample code has been implemented that enables signatures to be verified using test keys. This code can be deployed using a Docker container. For complete information, refer to README.

Error codes

When issuing a call to any in-scope API in either the Production or Sandbox environment, if the request is improperly formatted or does not include all required headers, an error will be returned. Refer to the following table for information about these errors.

Code Meaning
215000 Missing content-digest header
215001 Missing x-ebay-signature-key header
215002 Internal errors as fetching master key
215003 Internal errors as validating digital signaure
215101 Missing content digest
215102 Missing payload
215103 Parsing value of sha failed
215104 Base64 decoding sha failed
215105 Incorrect content digest of sha-256
215106 Incorrect content digest of sha-512
215107 Incorrect content digest of sha
215108 Content digest validation failed
215109 Missing parameters (internal error)
215110 Missing content-digest header
215111 Missing signature header
215112 Missing signature-input header
215113 Invalid timestamp in signature parameters
215114 The create time of signature parameters is not in right range
215115 Decrypting JWE failed
215116 Incorrect JWE format
215117 The appid in signature doesn't match app in token
215118 Missing pkey in JWE
215119 Decoding public key failed
215120 Signature validation failed
215121 Signature validation failed
215122 Signature validation failed

Digital Signature SDKs

To simplify the process of generating digital signature headers, eBay has developed the following SDKs. The SDKs also provides methods to validate digital signature headers.

Additional information about each of the SDKs is available in their respective README files.