registerClient | eBay Client Registration API

POST/client/register

Note: The Client Registration API is not intended for use by developers who have previously registered for a Developer Account on the eBay platform.
This call registers a new third party financial application with eBay.

Important! When calling the registerClient method, Third Party Providers (TPPs) are required to pass their valid eIDAS certificate to eBay via Mutual Transport Layer Security (MTLS) handshake Certificate Request messages.

A successful call returns an HTTP status code of 201 Created and the response payload.

Registering multiple applications

A regulated third party provider (identified by a unique organizationIdentifier) may register up to 15 different applications with eBay provided the unique software_id for each application is passed in at the time of registration.

Each registerClient call that passes in a unique software_id will generate new client_id and client_secret keypairs.

If a third party provider calls registerClient using a previously registered software_id, the existing client_id and client_secret keypairs are returned.

Note: For additional information about using an organizationIdentifier, refer to the following sections of ETSI Technical Specification 119 495

Section 5.2.1: Authorization Number or other recognized identifier for Open Banking;
Section 5.4: Profile Requirements for Digital Signatures.

Input

Resource URI

POST https://tppz.ebay.com/developer/registration/v1/client/register

This method is supported in Sandbox environment. To access the endpoint, just replace the tppz.ebay.com root URI with tppz.sandbox.ebay.com

URI parameters

This method has no URI parameters.

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

Note: There is no Authorization Header for this API.

In addition, this method requires you to include the Content-Type header and its value should be set to "application/json". See HTTP request headers- opens rest request components page for details.

OAuth scope

This request requires an access token created with the client credentials grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

See OAuth access tokens for more information.

Note: This API does not use an OAuth scope.

Request payload

Copy complete valid JSON to clipboard

{ /* ClientSettings */

"client_name" : "string",

"contacts" : [

"string"

"policy_uri" : "string",

"redirect_uris" : [

"string"

"software_id" : "string",

"software_statement" : "string"

}

Request fields

Input container/field	Type	Description
client_name	string	User-friendly name for the third party financial application. Note: Language tags are not supported. Therefore, `client_name` must be specified in English. Occurrence: Optional
contacts	array of string	This container stores an array of email addresses that can be used to contact the registrant. Note: When more than one email address is provided, the first email in the array will be used as the developer account's email address. All other email addresses will be used as general contact information. Occurrence: Optional
policy_uri	string	The URL string pointing to a human-readable privacy policy document that describes how the third party provider collects, uses, retains, and discloses personal data. Note: Only HTTPS URLs are supported for `policy_uri` strings. Note: This URL must not point to the eBay Privacy Policy. The value of this field must point to a valid and secure web page. Note: Language tags are not supported. Therefore, `policy_uri` will be displayed in English. Occurrence: Optional
redirect_uris	array of string	An array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows. Note: Only the first URI string from the list will be used.Note: Each redirection URI must be an absolute URI as defined by [RFC3986] Section 4.3. Occurrence: Required
software_id	string	A unique identifier string assigned by the client developer or software publisher to identify the client software being registered. Unlike `client_id` which should change between instances, the `software_id` should be the same value for all instances of the client software. That is, the `software_id` should remain unchanged across multiple updates or versions of the same piece of software. The value of this field is not intended to be human readable and is usually opaque to the client and authorization server. Occurrence: Optional
software_statement	string	The Software Statement Assertion (SSA) that has been issued by the OpenBanking identifier. Note: This value must be Base64 encoded and not plain JSON.Refer to RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol for complete information. Occurrence: Optional

Output

HTTP response headers

This call has no response headers.

Response payload

Copy complete valid JSON to clipboard

{ /* ClientDetails */

"client_id" : "string",

"client_id_issued_at" : "integer",

"client_name" : "string",

"client_secret" : "string",

"client_secret_expires_at" : "integer",

"contacts" : [

"string"

"grant_types" : [

"string"

"policy_uri" : "string",

"redirect_uris" : [

"string"

"scope" : "string",

"software_id" : "string",

"software_statement" : "string"

}

Response fields

Output container/field	Type	Description
client_id	string	A unique, eBay-generated id assigned to the third party application at the time it was registered. Occurrence: Always
client_id_issued_at	integer	The UNIX timestamp when the `client_id` was issued. This time is represented as the number of seconds from "1970-01-01T00:00:00Z", as measured in UTC, until the date/time of issuance. Refer to RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol for complete information. Occurrence: Always
client_name	string	User-friendly name for the third party financial application. Note: Language tags are not supported. Therefore, `client_name` will be specified in English. Occurrence: Conditional
client_secret	string	A unique OAuth 2.0 secret string assigned by eBay to the third party application at the time it is registered. This value should be unique for multiple instances of a client using the same `client_id`. This value is used by confidential clients to authenticate to the token endpoint, as described in OAuth 2.0 [RFC6749], Section 2.3.1. Note: `client_secret` is unique to the organization identifier of subject name which contains jurisdiction, NCA Id, and Authorization Number. Occurrence: Always
client_secret_expires_at	integer	The UNIX timestamp when the `client_secret` expires. Note: When a `client_secret` has been provided, this field is REQUIRED. A returned value of 0 indicates that the `client_secret` never expires. This time is represented as the number of seconds from "1970-01-01T00:00:00Z", as measured in UTC, until the expiration date and time. Refer to RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol section 3.2.1 for complete information. Occurrence: Always
contacts	array of string	This container stores an array of email addresses for representatives at the third party provider responsible for the application being registered. Occurrence: Conditional
grant_types	array of string	An array of OAuth 2.0 grant type strings that the client software can use at the token endpoint. Supported grant type values are: `authorization_code`: The authorization code grant type defined in OAuth 2.0, Section 4.1. `client_credentials`: The client credentials grant type defined in OAuth 2.0, Section 4.4. If the token endpoint is used in the grant type, the value of this parameter MUST be the same as the value of the `grant_type` parameter passed to the token endpoint defined in the grant type definition. Authorization servers may allow for other values as defined in the grant type extension process described in OAuth 2.0, Section 4.5. If omitted, the default behavior is that the client will use only the `authorization_code` Grant Type. Occurrence: Always
policy_uri	string	The URL string pointing to a human-readable privacy policy document that describes how the third party provider collects, uses, retains, and discloses personal data. Note: Only HTTPS URLs are supported for `policy_uri` strings. Note: This URL must not point to the eBay Privacy Policy. The authorization server should display this secure URL to the end-user if it is provided. The value of this field must point to a valid and secure web page. Note: Language tags are not supported. Therefore, `policy_uri` will be displayed in English. Occurrence: Conditional
redirect_uris	array of string	An eBay system-generated value assigned to the application. This value represents the redirect uri(s) submitted by the user either in the request payload (i.e., the `redirect_uris` field,) or the `software_statement`. Occurrence: Always
scope	string	String containing a space-separated list of scope values (as described in Section 3.3 of OAuth 2.0 [RFC6749]) that the client can use when requesting access tokens. The semantics of values in this list are service specific. Occurrence: Always
software_id	string	A unique identifier string provided by the client developer or software publisher at the time of registration that identifies the client software being registered. Unlike `client_id` which should change between instances, the `software_id` should be the same value for all instances of the client software. That is, the `software_id` should remain unchanged across multiple updates or versions of the same piece of software. Occurrence: Conditional
software_statement	string	The Software Statement Assertion (SSA), a JSON Web Token (JWT), that has been issued by the OpenBanking identifier. Refer to RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol for complete information. Occurrence: Conditional

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

Status	Meaning
201	Created
400	Bad Request
404	Not Found
500	Internal Server Error

Error codes

Unlike other eBay REST APIs, the Client Registration API does not return numeric error codes. Instead, errors are reported as text-based messages in the form of an Error followed by its corresponding Description. For example:

"error": "invalid_policy_uri", "error_description": "The policy_uri presented is invalid."

Refer to the following table for the list of errors and their descriptions.

error	error_description
invalid_policy_uri	The policy_uri presented is invalid.
invalid_contact_email	The value of one or more of the contact email addresses is invalid.
invalid_software_statement	The software statement presented is invalid.
invalid redirect_uri	The value of one or more redirection URIs is invalid or missing.
internal_server_error	There was a problem with an eBay internal system or process. Please retry.
invalid_request	Empty request or some field has error.
maximum_limit_keysets_reached	You have exceeded the maximum number of API keysets. For more information, see the API call reference documentation.
caller_not_registered	Caller is not registered
invalid_license	Invalid license
invalid_qtsp	Certificate not issued by a valid Qtsp
certificate_expired	Certificate expired
certificate_revoked	Certificate revoked
invalid_signature	Not a valid signature
role_mismatch	Role not matching
invalid_certificate	Invalid certificate
missing_certificate	Missing certificate
certificate_validation_error	Internal errors as validating client certificate
internal_service_error	Internal errors as calling another service

This call has no error codes.

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Register a new third-party client application

Sample 2: Illustrate error reporting for Client Registration API

Sample 1: Register a new third-party client application

This sample demonstrates how to register a new third party application with eBay.

Input

The required information is provided in the request payload.

POSThttps://tppz.ebay.com/developer/registration/v1/client/register

Output

If the call is successful, eBay returns an HTTP status code of 201 Created and the response payload.

Sample 2: Illustrate error reporting for Client Registration API

eBay's Client Registration API complies with RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol and as such adheres to all mechanisms it calls out.

Because RFC 7591 does not support numeric error codes, only text-based error information is returned.

This sample demonstrates the text-based system error response when invalid input data has been provided in the request payload.

Input

Required information is provided in the request payload.

In this example, an unsupported redirect_uris is provided (i.e., HTTP is not supported).

POSThttps://tppz.ebay.com/developer/registration/v1/client/register

Output

The system returns error information.