api-specs/developer_client_registration_v1_oas3.yaml
openapi: 3.0.0
info:
title: Developer Registration API
description: <span class="tablenote"><b>Note:</b> The Client Registration API is not intended for use by developers who have previously registered for a Developer Account on the eBay platform.</span><br/>The Client Registration API provides Dynamic Client Registration for regulated Third Party Providers (TPPs) who are, or will be, engaged in financial transactions on behalf of individuals domiciled in the EU/UK. This is required by the EU's Second Payment Services Directive (PSD2) which requires all regulated Account Servicing Payment Service Providers (ASPSPs) to provide secure APIs to access account and payment services on behalf of account holders.<br/><br/>A successful registration response returns a <b>HTTP 201 Created</b> status code with a JSON payload [RFC7519] that includes registration information.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v1.0.0
servers:
- url: https://tppz.ebay.com{basePath}
description: Production
variables:
basePath:
default: /developer/registration/v1
paths:
/client/register:
post:
tags:
- register
description: '<span class="tablenote"><b>Note:</b> The Client Registration API is not intended for use by developers who have previously registered for a Developer Account on the eBay platform.</span><br/>This call registers a new third party financial application with eBay.<br/><br/><div class="msgbox_important"><p class="msgbox_importantInDiv" data-mc-autonum="<b><span style="color: #dd1e31;" class="mcFormatColor">Important! </span></b>"><span class="autonumber"><span><b><span style="color: #dd1e31;" class="mcFormatColor">Important!</span></b></span></span> When calling the <b>registerClient</b> method, Third Party Providers (TPPs) are required to pass their valid eIDAS certificate to eBay via Mutual Transport Layer Security (MTLS) handshake <i>Certificate Request</i> messages.</p></div><br/>A successful call returns an HTTP status code of <b>201 Created</b> and the response payload.<h4>Registering multiple applications</h4>A regulated third party provider (identified by a unique <i>organizationIdentifier</i>) may register up to 15 different applications with eBay provided the unique <a href="#request.software_id ">software_id</a> for each application is passed in at the time of registration.<br/><br/>Each <b>registerClient</b> call that passes in a unique <a href="#request.software_id ">software_id</a> will generate new <a href="#response.client_id ">client_id</a> and <a href="#response.client_secret ">client_secret</a> keypairs.<br/><br/>If a third party provider calls <b>registerClient</b> using a previously registered <a href="#request.software_id ">software_id</a>, the existing <a href="#response.client_id ">client_id</a> and <a href="#response.client_secret ">client_secret</a> keypairs are returned.<br/><br/><span class="tablenote"><b>Note:</b> For additional information about using an <i>organizationIdentifier</i>, refer to the following sections of <a href="https://www.etsi.org/deliver/etsi_ts/119400_119499/119495/01.05.01_60/ts_119495v010501p.pdf " target="_blank ">ETSI Technical Specification 119 495</a><ul><li>Section 5.2.1: Authorization Number or other recognized identifier for Open Banking;</li><li>Section 5.4: Profile Requirements for Digital Signatures.</li></ul></span>'
operationId: registerClient
requestBody:
description: This container stores information about the third party provider's financial application that is being registered.
content:
application/json:
schema:
description: This container stores information about the third party provider's financial application that is being registered.
$ref: '#/components/schemas/ClientSettings'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/ClientDetails'
'400':
description: Bad Request
'404':
description: Not Found
'500':
description: Internal Server Error
components:
schemas:
ClientDetails:
type: object
properties:
client_id:
type: string
description: A unique, eBay-generated id assigned to the third party application at the time it was registered.
client_id_issued_at:
type: integer
description: The UNIX timestamp when the <code>client_id</code> 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 <a href="https://datatracker.ietf.org/doc/html/rfc7591#section-2.3 " target= "_blank ">RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol</a> for complete information.
format: int32
client_name:
type: string
description: User-friendly name for the third party financial application.<br/><br/><span class="tablenote"><b>Note:</b> Language tags are not supported. Therefore, <code>client_name</code> will be specified in English.</span>
client_secret:
type: string
description: 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 <code>client_id</code>. This value is used by confidential clients to authenticate to the token endpoint, as described in OAuth 2.0 [RFC6749], Section 2.3.1.<br/><br/><span class="tablenote"><b>Note:</b> <code>client_secret</code> is unique to the organization identifier of subject name which contains jurisdiction, NCA Id, and Authorization Number.</span>
client_secret_expires_at:
type: integer
description: The UNIX timestamp when the <code>client_secret</code> expires.<br/><br/><span class="tablenote"><b>Note:</b> When a <code>client_secret</code> has been provided, this field is <b>REQUIRED</b>.</span><br/>A returned value of <b>0</b> indicates that the <code>client_secret</code> never expires.<br/><br/>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 <a href="https://datatracker.ietf.org/doc/html/rfc7591#section-3.2.1 " target= "_blank ">RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol section 3.2.1</a> for complete information.
format: int32
contacts:
type: array
description: This container stores an array of email addresses for representatives at the third party provider responsible for the application being registered.
items:
type: string
grant_types:
type: array
description: 'An array of OAuth 2.0 grant type strings that the client software can use at the token endpoint. Supported grant type values are:<br/><ul><li><code>authorization_code</code>: The authorization code grant type defined in OAuth 2.0, Section 4.1.</li><li><code>client_credentials</code>: The client credentials grant type defined in OAuth 2.0, Section 4.4.</li></ul>If the token endpoint is used in the grant type, the value of this parameter <b>MUST</b> be the same as the value of the <code>grant_type</code> parameter passed to the token endpoint defined in the grant type definition. Authorization servers <b>may</b> 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 <code>authorization_code</code> Grant Type.'
items:
type: string
policy_uri:
type: string
description: 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.<br/><br/><span class="tablenote"><b>Note:</b> Only HTTPS URLs are supported for <code>policy_uri</code> strings.</span><br/><span class="tablenote"><b>Note:</b> This URL <b>must not</b> point to the eBay Privacy Policy.</span><br/>The authorization server should display this secure URL to the end-user if it is provided. The value of this field <b>must</b> point to a valid and secure web page.<br/><br/><span class="tablenote"><b>Note:</b> Language tags are not supported. Therefore, <code>policy_uri</code> will be displayed in English.</span>
redirect_uris:
type: array
description: 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 <code>redirect_uris</code> field,) or the <code>software_statement</code>.
items:
type: string
scope:
type: string
description: 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.
software_id:
type: string
description: A unique identifier string provided by the client developer or software publisher at the time of registration that identifies the client software being registered.<br/><br/>Unlike <code>client_id</code> which should change between instances, the <CODE>software_id</code> should be the same value for all instances of the client software. That is, the <code>software_id</code> should remain unchanged across multiple updates or versions of the same piece of software.
software_statement:
type: string
description: The Software Statement Assertion (SSA), a JSON Web Token (JWT), that has been issued by the OpenBanking identifier. Refer to <a href="https://datatracker.ietf.org/doc/html/rfc7591#section-2.3 " target= "_blank ">RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol</a> for complete information.
description: This container stores information about the third party provider's financial application that has been registered with eBay.
ClientSettings:
type: object
properties:
client_name:
type: string
description: User-friendly name for the third party financial application.<br/><br/><span class="tablenote"><b>Note:</b> Language tags are not supported. Therefore, <code>client_name</code> must be specified in English.</span>
contacts:
type: array
description: This container stores an array of email addresses that can be used to contact the registrant.<br/><br/><span class="tablenote"><b>Note:</b> 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.</span>
items:
type: string
policy_uri:
type: string
description: 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.<br/><br/><span class="tablenote"><b>Note:</b> Only HTTPS URLs are supported for <code>policy_uri</code> strings.</span><br/><span class="tablenote"><b>Note:</b> This URL <b>must not</b> point to the eBay Privacy Policy.</span><br/>The value of this field <b>must</b> point to a valid and secure web page.<br/><br/><span class="tablenote"><b>Note:</b> Language tags are not supported. Therefore, <code>policy_uri</code> will be displayed in English.</span>
redirect_uris:
type: array
description: An array of redirection URI strings for use in redirect-based flows such as the authorization code and implicit flows.<br/><br/><span class="tablenote"><b>Note:</b> Only the first URI string from the list will be used.</span><span class="tablenote"><b>Note:</b> Each redirection URI <b>must</b> be an absolute URI as defined by [RFC3986] Section 4.3.</span>
items:
type: string
software_id:
type: string
description: A unique identifier string assigned by the client developer or software publisher to identify the client software being registered.<br/><br/>Unlike <code>client_id</code> which should change between instances, the <CODE>software_id</code> should be the same value for all instances of the client software. That is, the <code>software_id</code> 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.
software_statement:
type: string
description: The Software Statement Assertion (SSA) that has been issued by the OpenBanking identifier.<br/><br/><span class="tablenote"><b>Note:</b> This value <i>must be</i> <b>Base64</b> encoded and not plain JSON.</span>Refer to <a href="https://datatracker.ietf.org/doc/html/rfc7591#section-2.3 " target= "_blank ">RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol</a> for complete information.
description: This container stores application-specific information that is provided at the time of registration.
Error:
type: object
properties:
category:
type: string
description: Identifies the type of erro.
domain:
type: string
description: Name for the primary system where the error occurred. This is relevant for application errors.
errorId:
type: integer
description: A unique number to identify the error.
format: int32
inputRefIds:
type: array
description: An array of request elements most closely associated to the error.
items:
type: string
longMessage:
type: string
description: A more detailed explanation of the error.
message:
type: string
description: Information on how to correct the problem, in the end user's terms and language where applicable.
outputRefIds:
type: array
description: An array of request elements most closely associated to the error.
items:
type: string
parameters:
type: array
description: An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.
items:
$ref: '#/components/schemas/ErrorParameter'
subdomain:
type: string
description: 'Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc.'
description: This type defines the fields that can be returned in an error.
ErrorParameter:
type: object
properties:
name:
type: string
description: The object of the error.
value:
type: string
description: The value of the object.
securitySchemes:
api_auth:
type: oauth2
description: The security definitions for this API. Please check individual operations for applicable scopes.
flows:
clientCredentials:
tokenUrl: https://api.ebay.com/identity/v1/oauth2/token
scopes:
https://api.ebay.com/oauth/api_scope: View public data from eBay