Account Holder API

Creating an API Login

Please sent an email to [e-mail] and request an UAT API login to be created and a list of IPs to be whitelisted. An API login and API password will be created for account holders and emailed separately to the account holder. 

Once an user is comfortable using our API in our UAT environment we can proceed with approving an API login in Production. All account holders must start API testing in the UAT environment. Note, you will only be able to have one API login per environment. You can add multiple IPs tied to the one API login within reason. 

The next step will be for the NAR administrator to create Client_ID and Client_Secret which you will need to access the API. They will be emailed separately for confidentiality reason. 

NAR API Overview 

The NAR Registry has released a set of user-facing APIs. This initial release is focused on APIs necessary to transact certificates. These RESTful APIs include endpoints for the following: 

1. GET Certificate Holdings 
   Returns certificate holdings belonging to the specified account holder(s). 

2. GET List of counterparties 
   Returns a list of accounts from the registry. These accounts may be specified as counterparties to certificate transfers. 

3. POST Certificate Transfers 
   Initiate the transfer of certificates to another account holder. 

4. GET Pending Transfers 
   Returns a list of pending transfers (incoming and outgoing). 

5. POST Certificate Transfer Actions 
   Take action on pending transfers. Confirm or reject incoming transfers or withdraw outgoing transfers. 

6. GET Sub-Accounts 

Returns a list of sub-accounts (Active, Retirement, etc.). These sub-accounts can be specified for sub-account transfers and retirements 

7. POST Sub-Account Transfers 
   Transfer certificates within an account. 

8. POST Certificate Retirement 
   Initiate retirements for an account. 

Account Managers can create API Logins for their own accounts or delegate another account holder to act on their behalf through the API.  

Further technical documentation will be provided detailing how users will authenticate against the API (OAuth2), and the details of each endpoint. See our portal here.

https://developer.xpansiv.com/developer-portal/nar-registry/

Using the NAR API

Like most APX APIs, the NAR API is RESTful, with Oauth2 authentication. 

Authentication

The way OAuth2 authentication works, is that the user must submit their credentials to an authentication server, which should return a short-lived OAuth token. This token must be provided when interacting with the actual NAR API endpoints. Since the token expires in 29 seconds, users will likely get a new token before every request.

Here is a technical document about how our authentication protocol works. This can be shared with AHs.

Postman

Postman is an application that allows non-technical/semi-technical people to interact with RESTful APIs (and other types as well, e.g. SOAP APIs). Using Postman is a great way to understand our APIs, and to help users troubleshoot API issues.

To get started using Postman for NAR APIs:

1. Download Postman (can also use web-based version)
2. Open the application and Import APX/NAR-specific configurations (All in this folder):
   1. NAR UAT ‘Environment’  
      This is the specific variables for the NAR UAT environment, such as URLs, credentials, etc., and variables to support the Collections that you are about to import. NOTE: You will have to update the credentials after you import: 
      

NOTE: THE TOKEN URL FOR UAT IS DIFFERENT FOR APX USERS ON THE VPN VS USERS ON THE PUBLIC INTERNET. ON THE PUBLIC INTERNET, THERE IS NO HYPHEN BEFORE ‘UAT.APX.COM’

1. Get OAuth Token ‘Collection’ 
   This collection is useful just for testing credentials. You can plug in credentials and verify that they will return an Oauth Token, which is very useful when helping users troubleshoot issues.
2. NAR ‘Collection’ 
   The actual NAR-specific API endpoint methods. This should include a collection-level ‘pre-request script’ that will retrieve an OAuth token automatically whenever you make a request. After you import, the ‘Authorization’ tab of the Collection should look like this: 
   

And each endpoint should look like this: 

1. Once you have imported everything, select the NAR UAT environment in the upper right corner, open the GET Ping method of the collection, and click Send. Your result should look like this: 
   

A successful response means that you have retrieved an OAuth token and successfully used that token to call the Ping endpoint. This endpoint is simply for connectivity testing as does not take any actions in the registry.

1. You can experiment with the other methods. The details of all of them is beyond the scope of this document, but referring to the Swagger page is recommended.

Common User Issues

Many account holders have issues getting started with API connectivity. They extent of their difficulties depends on how technically sophisticated the user is. Often times, semi-technical folks will be tasked with building API integration, and will struggle with some aspects. Many folks alsouse Postman, which may enable you to better help them. 

WARNING: if you try to help a user by exporting your Postman environment and sending it to them, it will include the credentials that you currently have.

The majority of issues are related to authentication. People struggle with:

• Using the right credentials (username/password AND clientId/clientSecret).
• Properly encoding the clientId/clientSecret.
• Once they can get a token, using the token correctly in their request AND using an un-expired token (tokens expire after 29 seconds).
• Not whitelisting the correct IP addresses.

User getting HTTP 401 error when hitting NART API endpoint

One of two problems:

1. They are not including an Oauth Token in their request. (no response payload when this happens). 
2. They are using an expired token. Response payload looks like: 
   {"error": "invalid_token",

"error_description": "Cannot decode access token"}

 

User cannot get an OAuth token

1. Get the users username/password AND clientId/clientSecret. You may ask to re-set their API Password in the NAR UI so that you know you have it.
2. Enter the Credentials into your NAR UAT environment in Postman.
3. Use the Get OAuth Token Collection/method.

If you get a token back, then you know that you have the correct credentials and the problem is likely one of the following:

1. Token request is built incorrectly,. You can try to help them figure it out, or refer them back to NAR API – Oauth2 Authentication Protocol. 
2. They are pointed to the wrong token URL (these are also in the doc). NOTE: THE TOKEN URL FOR UAT IS DIFFERENT FOR APX USERS ON THE VPN VS USERS ON THE PUBLIC INTERNET. ON THE PUBLIC INTERNET, THERE IS NO HYPHEN BEFORE ‘UAT.APX.COM’

User Gets Token and includes with request, but get HTTP 403 when hitting API endpoint

This is likely an issue with IP Whitelisting. You can ask the user to please double check that they have whitelisted the IP of the machine they are using to make the API request (may be a different machine than the one that got the OAuth token!).

Non-authentication endpoint-specific errors

Generally there should be decent error messages that explain the problem, although there are nearly endless ways that users can screw up their request.