Getting Started

The guide will outline all the steps required to integrate with Morgan Stanley APIs. The table below lists the different environments that are available for integration.

Developer Portal

Get started with the integration by trying out APIs with mock data. Only accessible via the Developer Portal.

api-sandbox.morganstanley.com

UAT

Test end to end integration using UAT data

api-uat.morganstanley.com

Production

Connect and integrate with live Morgan Stanley APIs

api.morganstanley.com

Setting up a Client Application

To connect to Morgan Stanley's API offering the OAuth2 Authorization Framework is used. We currently support only the Client Credentials Grant, for use by client owned applications acting on their own behalf.

Suggested Knowledge

Before proceeding with registering a Client Application at Morgan Stanley it is suggested that you understand the OAuth2 protocol and the terminology.

The Microsoft's OAuth2 Client Credentials Grant describes how to use the Microsoft Azure Identity Platform.

Registering a Client Application

To access the Morgan Stanley API and use the Client Credentials grant it is required to use an RSA keypair (Microsoft, our identity partner, do not currently support Elliptic Curve signatures). A new private key should be generated for each of your Client Applications.

The private key is then used to create a signed JWT assertion (a signed claim that identifies your application). The assertion is used to authenticate your application (OAuth2 Client) with the OAuth token service. The token service responds with an Access token that is used to access the Morgan Stanley APIs.

IMPORTANT: This private key identifies your application and it is your responsibility to keep it secure. If it is leaked you are opening yourself up to others impersonating your applications identity which can cost you financially and reputationally

To verify the application, it is required that a public key is provided to Morgan Stanley to validate the signed claim. The public key is represented by a self-signed certificate generated using the private key. The certificate is associated by Morgan Stanley with the client application configuration. The certificate provides a wrapper around the public key that carries meta-data such as expiry time.

It is not necessary to use a public Certificate Authority to sign your certificate

This certificate can be emailed to Morgan Stanley to be associated with your application. The certificate is public and poses no security risks if intercepted.

A way to generate a private key and a public certificate is the following

Generate the Private Key

It is possible to add a passphrase to your private key. This sample does not add a passphrase

openssl genrsa -out private_key.pem 4096

This will generate a 4096 bit RSA private key.

IMPORTANT: Keep this safe do not share it

Generate the self-signed Certificate

Note in the below you will need to set the number of days that you would like the certificate to be valid for as a whole number.

openssl req -new -x509 -key private_key.pem -out public_key.cer -days <days-to-expiry> -sha512 -subj "/CN=myapp"

This creates a certificate using a SHA512 message digest

Email Morgan Stanley the public Certificate

Email this public_key.cer to your Morgan Stanley contact and state the environment that you would like to integrate with (UAT/PROD).

For details on self-service certificate management please speak to your Morgan Stanley contact.

Wait for Your client_id and the Certificate Thumbprint

You will receive back from your Morgan Stanley contact your unique client_id and the uploaded certificate thumbprint.

It is important that you verify this thumbprint matches your public_key.cer thumbprint. To do this you can create a thumbprint for your certificate by running the following:

openssl x509 -in public_key.cer -fingerprint -noout

Confirm that this matches the thumbprint that was sent to you by your Morgan Stanley contact. This then confirms both yourself and Morgan Stanley agree on the key that will be used.

Create an Application

Two sample applications have been created that can be used to get started with.

This sample uses the jq tool which is an open source and available at https://github.com/stedolan/jq.

A curl request can be performed against the API endpoint. First download generate-client-assertion.sh and ensure it is available when running the request below:

# Set the variables for the query 
client_id="########-####-####-####-############"
private_key_file="C:\Client-instructions\new-test-keys\private_key.key"
public_cer_file="C:\Client-instructions\new-test-keys\public_key.crt"
scope="<Scope sent from contact>"

# Create the assertion token required to get an Access token
TOKEN=$(./generate-client-assertion.sh $client_id $private_key_file $public_cer_file)

# Request an access token from the Azure AD token endpoint
ACCESS_TOKEN=$(curl https://login.microsoftonline.com/api.morganstanley.com/oauth2/v2.0/token -d scope=$scope -d client_id=$client_id -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer -d client_assertion=${TOKEN} -d grant_type=client_credentials | jq --raw-output '.access_token')

# Send request to API
curl -X GET -v --header "Authorization: Bearer $ACCESS_TOKEN" --header 'Accept: application/json' https://api.morganstanley.com/hello/services'