Follow

Authentication Methods

In our Overview Article, we covered Basic Authentication. However, to be thorough, I will provide the same material here as well as cover the other Authentication types available. Feel free to skip over Basic Authentication if you are already familiar with the 101 documentation.

There are three authentication options available to you.

  • Basic Authentication
  • UserKey Authentication
  • UserToken Authentication

Authenticating via Basic Authentication

Basic Authentication, as you might have expected, requires credentials. A Username, Password, and an APIKey to be specific!

While the Username and Password should not need an introduction, you might not know exactly what our APIKey represents. Simply put, the ApiKey is a unique identifier assigned to a partner and allows access to the API.  Every APIKey is unique and has its own data associated with it. (see sample record below)

APIKey Record

<APIKey>G5555F31-56Z2-62X7-9PSG-553E0MCD8ATG2</APIKey>
<Name>Redtail Technology</Name>
<URL>http://www.redtailtechnology.com</URL>
<Institution>0</Institution>
 

Ok, so now you should be wondering, How do I supply the credentials?

Below, you can see that the credentials are supplied in the request header as a string, with each credential separated by a single colon.  Don't worry! The credentials are secured via SSL.

"APIKey:Username:Password"
"G5555F31-56Z2-62X7-9PSG-553E0MCD8ATG2:CoolGuy65:L@zypass"

 

When supplying the credentials, you will want to use base64 encoding to alleviate any woes related to incompatible characters, as well as specify the Basic authentication type. See bolded string in request header example below.(C#)

//using system.net;

HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create("https://api2.redtailtechnology.com/crm/v1/rest/contacts/384843/notes"); req.Headers[System.Net.HttpRequestHeader.Authorization] = "Basic " + Convert.ToBase64String(System.Text.Encoding.Default.GetBytes("G5555F31-56Z2-62X7-9PSG-553E0MCD8ATG2:CoolGuy65:L@zypass")); req.Method = "GET"; req.ContentType = "text/xml";

Your Credentials

While we do provide credentials specific to our partners, for the sake of this example I am providing a working set of credentials for our production server. If your team does not already have a set of credentials for both environments(development and production), please send your request to -> Chris@redtailtechnology.com

Here's a set to play with while you're emailing me...

APIKey - "6C135EDF-C37C-4039-AEF3-5DFC079F9E6A"
Username - "Statementone"
Password - "sonedemo"
UserKey - "B7B4BCDD-67C8-449C-B1D4-C1AAFE49703D"
SecretKey - "D81FC882442D4F0988E152B96A646623"

 

Authenticating via UserKey

UserKey Authentication requires an APIKey and a UserKey. The UserKey is a unique Identifier for an individual user and remains constant regardless if a User decides to change his or her password. As such, authenticating through the UserKey is ideal once you've obtained the user's UserKey.

Supplying the credentials is similar for all of our authentication method types. As seen in the Basic Authentication method, the credentials are colon delimited.

"APIKey:UserKey"
"6C135EDF-C37C-4039-AEF3-5DFC079F9E6A:B7B4BCDD-67C8-449C-B1D4-C1AAFE49703D"

 

And just as before, when supplying the credentials you will want to use base64 encoding to alleviate any woes related to incompatible characters. However, this time around, you will want to specfiy the authentication type in the request header as "UserkeyAuth " Please see example below.(C#)

 

//using system.net;

HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create("https://api2.redtailtechnology.com/crm/v1/rest/contacts/384843/notes"); req.Headers[System.Net.HttpRequestHeader.Authorization] = "Userkeyauth " + Convert.ToBase64String(System.Text.Encoding.Default.GetBytes("6C135EDF-C37C-4039-AEF3-5DFC079F9E6A:B7B4BCDD-67C8-449C-B1D4-C1AAFE49703D"));
req.Method = "GET"; req.ContentType = "text/xml";


Authenticating via UserToken

UserToken authentication requires a UserToken and an APIKey. A UserToken is a security token composed of a timestamp, time restriction, and a Userkey. The timestamp and time restriction renders the UserToken time-sensitive. The allotted time for a UserToken to be processed is 5 minutes.

It may be helpful to think of the UserToken, before being encrypted against the Secret Key,  as being mathematically equivalent to the following...


UserToken = (Relevancy Period) + (UserKey)

If needed, we can substitute a Username and Password to use in place of a UserKey

UserToken = (Relevancy Period) + (Username + Password)

 

 The sum of all its parts represents a security token specific to a user with a precise relevancy of 5 minutes.(read on to see the UserToken Creation Function)

 

"APIKey:UserKey"
"6C135EDF-C37C-4039-AEF3-5DFC079F9E6A:" & CreateUserToken("B7B4BCDD-67C8-449C-B1D4-C1AAFE49703D")

As is the case with all of these methods, the credentials are colon delimited.  However, as you can see, we will need to call a function to create a UserToken for us. You will also notice that, yet again, we will be converting the string to base64. When using our authentication methods, be sure you are specifying the correct Authentication type at the beginning of each string.

 

//using system.net;

HttpWebRequest req = (HttpWebRequest)HttpWebRequest.Create("https://api2.redtailtechnology.com/crm/v1/rest/contacts/384843/notes");
req.Headers[System.Net.HttpRequestHeader.Authorization] = "UsertokenAuth " & Convert.ToBase64String(System.Text.Encoding.Default.GetBytes("6C135EDF-C37C-4039-AEF3-5DFC079F9E6A:" & CreateUserToken(SUserKey)));
req.Method = "GET"; req.ContentType = "text/xml";

 

Below are a Create Token and Encryption, respectively, which you are welcome to use.

 

private string CreateUserToken(string UserKey)
{

	string UserToken = null;
	UserToken = Strings.Format(DateAndTime.Now.AddMinutes(5).ToUniversalTime(), "yyyy-MM-ddTHH:mm:ssZ") + "|" + UserKey;
	return Encrypt(UserToken, SecretKey);

}

This function declares the UserToken Variable, specifies the value, and then calls the Encrypt Function to encrypt the UserToken against the Secret Key.

 

Alternatively, If you do not have the UserKey, you can always substitute the UserKey for a UserName and Password to create a UserToken. 

 

 

 For your purposes, specified below are the encryption fields KeySize, Padding, and Mode.

KeySize=256

Padding=PKCS7      

Mode=ECB

 

The following is a working VB.net Function for UserToken Creation using  UserName and Password in lieu of a UserKey


private string Encrypt(string Input, string Key) { byte[] buff = ASCIIEncoding.ASCII.GetBytes(Input);

RijndaelManaged aes = new RijndaelManaged();
aes.KeySize = 256;
aes.Key = ASCIIEncoding.ASCII.GetBytes(Key);
aes.Padding = PaddingMode.PKCS7;
aes.Mode = CipherMode.ECB;

System.IO.MemoryStream memStream = new System.IO.MemoryStream();
CryptoStream cypStream = new CryptoStream(memStream, aes.CreateEncryptor(), CryptoStreamMode.Write);
cypStream.Write(buff, 0, buff.Length);
cypStream.Close();
return Convert.ToBase64String(memStream.ToArray()); }

 

 

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

Powered by Zendesk