Getting Started

Authentication

In order to ensure data security, BNSF uses certificate-based Mutual Authentication (also known as mTLS, or two-way authentication) to allow our customers to validate our identity (Server Authentication), to allow BNSF to validate our customer's identities (Client Authentication) and to protect/encrypt the transfer of data.

To achieve Client Authentication, we require certificates to be issued from trusted Certificate Authorities. We accept Domain Validation, Organization Validation, Extended Validation and S/MIME (email) certificates. Domain Validation and S/MIME are the least expensive options. You should read about TLS/SSL and S/MIME certificates to better understand your options.

Here are links to some of the certificate offerings we accept:

• Entrust TLS/SSL, S/MIME
• Sectigo DV, S/MIME
• GoDaddy DV, S/MIME
• Comodo DV, S/MIME
• DigiCert DV, Client Certificate Options

*** Note: We do not accept certificates that are self-signed, private, or those issued by Let's Encrypt, webCARES or CloudFlare.com.

Certificate Requirements:

• Effective no longer than 36 months.
• Organization Name should be the company name that appears on your BNSF.com profile.
• Common Name should be your domain name for TLS/SSL certificates. For S/MIME, use your email address.
• Domain name must match the email address domain on your BNSF.com profile.
• Extended Key Usage must include Client Authentication (OID 1.3.6.1.5.5.7.3.2).

For more information about mutual authentication, please refer to the Mutual Authentication article in Wikipedia.

Onboarding

You will need to get a BNSF.com userid before registering for the BNSF Customer API. Once you have your userid, you can use Message Us to register.

Postman

Once you are setup and approved to start using our APIs, you can conduct a test to see how fast and easy it is via a collaboration platform called Postman. To get stared with Postman, simply follow these steps:

• Set up your client certificate by following Postman's instructions.
• Host: api-trial.bnsf.com
• Port: 6443
• Use the Choose File buttons to set your CRT and KEY files. Passphrase is optional.
• Once your client certificate is set up, create a new request in Postman as follows:
1. Set method to GET
2. Set the request URL to https://api-trial.bnsf.com:6443/v1/cars
3. Add this header: Content-Type: application/json
4. Hit Send
5. If everything is setup properly, you should get a response.
6. You can change steps 1 and 2 to try other services. See Developer's Console

Troubleshooting Tips

• When trying to connect or download the certificate, make sure you are using port 6443
• Make sure your certificates are in PEM format and unencrypted in Postman
• Run a Health Check by requesting https://api-trial.bnsf.com:6443/healthcheck. You should get:
  <status>OK</status>
• Use Powershell's Test-Netconnection to verify you are not blocked by a firewall

C:\> powershell Test-Netconnection -ComputerName "api-trial.bnsf.com" -Port 6443
TcpTestSucceeded : True

You're all set!

If you need any assistance, please reach out to the support team using the information below.