Welcome to the eMoney Access APIs. This page will walk you through the process of connecting to the API step by step.

Note that this process requires a basic understanding of JSON Web Tokens (JWT). Here is a quick introduction.

This guide is divided into 2 sections. Section 1 walks you through the steps required for gaining access to the eMoney Access APIs. This needs to be done only once. Section 2 will outline the steps required to programmatically connect to the eMoney Access API. 

 

Section 1: Gaining access to the eMoney Access API.

  • Purchase an X.509 CA certificate and export the public key and private key to separate files
  • Send the public key to your eMoney representative
  • eMoney representative will provide a Client Id and an API Key

Once you have the Client Id and the API key provided by an eMoney representative, you can connect to the eMoney Access API.

Section 2: The connection process consists to the following steps. This should be done via your programming language of choice. We provide examples in C#.

  1. Generate a JWT
    1. Generate a Client Assertion JSON Web Token (JWT) using the Client ID and your private key file (*.pfx) at https://signin.emaplan.com/connect/token
  2. Generate an access token
    1. Send a POST request to the authenticate against this endpoint https://signin.emaplan.com/connect/token
    2. Extract the access_token as a string from the response to the POST request
  3. Connecting to the API.
    1. Use the access token as a Bearer Authorization header for your request.
    2. Add a header “apikey” with the eMoneyAPI key that the eMoney representative provided.
    3. Send the API request to the eMoney Access API
Possible Error Response Parameters
Parameter Description Required
error Error Code  Yes
error_description Human-readable ASCII encoded text description of the error. No
error_uri

URI of a web page that includes additional information about the error.

No
state OAuth 2.0 state value. REQUIRED if the Authorization Request included the state parameter. Set to the value received from the Client. Conditionally

 

Possible Error Codes

These are the possible error codes that can be returned in the "error" parameter from the response.

Error Description
invalid_request The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.
invalid_client Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported. If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client.
invalid_grant The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.
unauthorized_client The authenticated client is not authorized to use this authorization grant type.
unsupported_grant_type The authorization grant type is not supported by the authorization server.

 

Possible Error Response Parameters

Header

The header includes information about the key and algorithm used to sign the payload like below. This is required.

Client Assertion Form Data

{

    "alg": "RS256",

      // The "alg" (algorithm) parameter identifies the algorithm

      // intended for use with the key.


    "kid": "kh6XrTN6WjzvhH8Lk6sKieiP5hw",

      // The "kid" (key ID) parameter is used to match a specific key.

      //This is the Fingerprint of the Cert


    "typ": "JWT"

      // The "typ" is the Token Type

}

 

Payload

The associated payload should look like this. All fields are required. Using your Client ID provided by the eMoney team, replace the below tag {Client ID} with your Client ID. The Subject Claim (sub), Expiry (exp), Issuer (iss) and Audience (aud) are all required in the payload. The Audience claim should be the OAuth server token endpoint that you received from the eMoney team.

Client Assertion Payload

{

    "sub": "{Client ID}",

      // This is the ID that eMoney will provide in the

      // configuration phase



    "exp": 1514301769,

      // The expiration time (exp) claim identifies the expiration

      // time on or after which the JSON web token must not be accepted

      // for processing. We require that the expiration be set to

      // no more than one day in advance.



    "iss": "{Client ID}",

      // The issuer (iss) claim identifies the principal that issued

      // the JSON web token.



    "aud": "https://signin-api-beta.emaadvisor.com/connect/token"

      //The audience (aud) claim identifies the recipients for which

      // the JSON web token is intended.

}

 

Signature

To create the signature, you have to take the encoded header, the encoded payload, a secret, the algorithm specified in the header, and sign that. This part will vary depending on the programming language you are using. Refer to examples below.

C# Example

using Microsoft.IdentityModel.Tokens;
using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;
using System.IdentityModel.Tokens.Jwt;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Security.Claims;
using System.Security.Cryptography.X509Certificates;

namespace eMoneyAPI
{
    internal class Program
    {
        private static void Main(string[] args)
        {
            /// Variables
            var privateCertificateFilename = "<YourCertificatePrivateKey.pfx>";
            var privateCertificatePassword = "<YourCertificatePassword>";
            var clientId = "<YourClientId>";
            var eMoneyAPIKey = "<YoureMoneyAPIKey>";

            // Generating the JWT Token
            var jwtSecurityTokenHandler = new JwtSecurityTokenHandler();
            var securityTokenDescriptor = new SecurityTokenDescriptor
            {
                Subject = new System.Security.Claims.ClaimsIdentity(new[]
                {
                    new Claim(JwtRegisteredClaimNames.Sub, clientId)
                }),
                SigningCredentials = new SigningCredentials(new X509SecurityKey(new X509Certificate2(privateCertificateFilename, privateCertificatePassword)), SecurityAlgorithms.RsaSha256Signature),
                Audience = "https://signin.emaplan.com/connect/token",
                Expires = DateTime.UtcNow.AddHours(1),
                Issuer = clientId
            };
            var clientAssertionJwt = jwtSecurityTokenHandler.CreateEncodedJwt(securityTokenDescriptor);
            Console.WriteLine("JWT Token");
            Console.WriteLine(clientAssertionJwt);

            // Generating the Access token
            var requestContent = new FormUrlEncodedContent(new Dictionary<string, string>
                {
                    { "grant_type", "client_credentials" },
                    { "client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" },
                    { "client_assertion", clientAssertionJwt },
                    { "scope", "API" }
                });
            var httpResponseMessage = new HttpClient().PostAsync("https://api.emoneyadvisor.com/connect/token", requestContent).Result;
            var jObject = JObject.Parse(httpResponseMessage.Content.ReadAsStringAsync().Result);
            var accessToken = jObject["access_token"].ToString();
            Console.WriteLine("Access Token");
            Console.WriteLine(accessToken);

            // API Request to list all the users
            var httpClient = new HttpClient();
            var requestMessage = new HttpRequestMessage
            {
                RequestUri = new Uri("https://api.emoneyadvisor.com/public/v1/users"),
                Method = HttpMethod.Get
            };
            requestMessage.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
            requestMessage.Headers.Add("apikey", eMoneyAPIKey);
            var response = httpClient.SendAsync(requestMessage).Result;
            Console.WriteLine("GET Users Response");
            Console.WriteLine(JValue.Parse(response.Content.ReadAsStringAsync().Result).ToString(Newtonsoft.Json.Formatting.Indented));
        }
    }
}