Domain Registration API is used to register your web server, the first step of three in setting up your systems to receive and process notification events. This page guides you through the integration of this API.

OpenAPI specification

Refer to the Domain Registration API Reference to help you integrate the API. There are two required parameters in the API request body, tls_certificate_thumbprint and expiry_date_time. The API response includes a SwiftNet domain name, such as 51d57890-54d0-41ef-bcfd-b983ad4c647551d57890-54d0-41ef-bcfd-b983ad4c6475 is a random generated UUIDv4 value for unique naming..hooks.swiftnet.sipn.swift.com. You can choose to setup multiple domains depending on your requirement.

tls_certificate_thumbprint

tls_certificate_thumbprint is a unique identifier of the certificate for the web server receiving inbound notifications from the Swift API platform. It is used during TLS handshake with the Swift API Gateway.

The thumbprint or fingerprint is generated by applying SHA-256 cryptographic hash function to the certificate data and its signatures. You can use openssl or keytool to extract SHA256 thumbprint of the certificate, and then remove : from the thumbprint.

For example, if the certificate thumbprint is the following:

tls_certificate_thumbprint should be:

expiry_date_time

The other required request body element is expiry_date_time beyond which the domain can no longer be used. This value should be in UTC format.

Choose developer tools

Looking for a faster and easier way to integrate? Consider using one of the developer tools designed to simplify the consumption of API-based services available on the Swift platform. Build your application with Swift SDK to help you with lower-level application plumbing, which includes authentication, authorisation, signing and error handling. Alternatively, consider using Swift Microgateway to configure, monitor all API calls you make on Swift and capture inbound API requests. Finally, Swift zero-footprint is an option that provides reference implementations so that you can create your own SDK or utilities.

Test Domain Registration API in Pilot

Swift Pilot environment closely resembles the Live environment, and it is intended to fully qualify your API integration. Follow the steps below to access the Domain Registration API Pilot testing environment.

Step 1: Create an app for Pilot

Create an app for testing in the Pilot environment and select Swift Notification API from the list of API products. Inside the app are consumer-key and consumer-secret which are the application credentials used to identify the application calling the API. After creating the app, promote the app to the Pilot environment.

Step 2: Create Certificate & assign RBAC role for Pilot

Domain Registration API supports the use of Business certificates and Channel certificates when signing the JWT in the authorisation API call. After creating the certificate, assign the RBAC role swift.notif!p/consumer to the certificate.

Step 3: Making your first test API call in the Pilot environment

After completing the steps above, you now have the credentials you need to access the Domain Registration API in the Pilot environment. Refer to Authentication to learn how to use the credentials you created above to start testing your integration with this API in Pilot.

Go Live

After successfully testing the Domain Registration API in Pilot, follow the steps below to start using this API in Live.

Step 1: Create an app for Live

Promote the app you created to the Live environment or create a new app for the Live environment. If you decided to create a new app, select Swift Notification API from the list of API products. After the app is created, promote the app to the Live environment.

Step 2: Create Certificate & assign RBAC role for Live

Follow the same process for creating the certificate for Pilot testing. Domain Registration API supports the use of Business certificates and Channel certificates when signing the JWT in the authorisation API call. After creating the certificate, assign the RBAC role swift.notif/consumer to the certificate for Live.

Step 3: Making your first test API call in Live

Swap out the credentials you used for Pilot with Live credentials and start using the Domain Registration API in your Live applications. When in doubt, refer to Authentication to learn how to use your Live credentials to access this API in Live.