Domain Registration API
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.
- In case of using HTTP Forward Proxy, you must configure HTTPS Reverse Proxy on the same host for receiving inbound notifications. If your HTTPS Reverse Proxy terminates TLS, you must provide the thumbprint of the Reverse Proxy certificate during domain registration.
- In case of using HTTPS Reverse Proxy in pass-through mode, then the web server or the Swift Microgateway (if used) certificate thumbprint should be provided during domain registration.
- If case of using Swift Microgateway without HTTPS Reverse Proxy, then the thumbprint of the Swift Microgateway certificate should be provided during domain registration.
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:
56:CF:E7:00:33:AF:F0:28:EF:25:96:F1:30:D8:25:C8:F3:60:9B:3C:68:9B:09:C2:DF:7C:3B:6F:2A:03:4C:EFtls_certificate_thumbprint should be:
56CFE70033AFF028EF2596F130D825C8F3609B3C689B09C2DF7C3B6F2A034CEFexpiry_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.
This step should be completed by a security officerClick to learn more about SWIFTNet PKI Security Officer registration in the Knowledge Centre..
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.
You should promote the app to Pilot first and then Live.
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.
This step should be completed by a security officerClick to learn more about SWIFTNet PKI Security Officer registration in the Knowledge Centre..
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.