Authentication

Overview

Authorization:  A security mechanism to determine access levels or user privileges related to system resources including files, services, computer programs, data and application features. This is the process of granting or denying access to a network resource which allows the user access to various resources based on the user's identity.

Authentication: The process of verifying the identity of a person or device. A common example is entering a username and password when you log in to a website. Entering the correct login information lets the website know 1) who you are, and 2) that it is actually you accessing the website.

APIs vary in the way they authenticate users. Some APIs just require you to include an API key in the request header, while other APIs require elaborate security due to the need to protect sensitive data, prove identity, and ensure the requests aren’t tampered with.

API keys

Before you can make requests with Vitalware APIs, you need to register for a Vitalware application key.

• An API key is a long string that you include either in the request URI or in the request header.

• The API key mainly functions as a way to identify the person making the API call (authenticating you to use the API). The API key is associated with a specific app that you register.

Vitalware API keys are used for any of the following:

• Authenticate calls to the API to registered users only.

• Vitalware can track who is making requests.

• Track usage of the API.  This provides Vitalware insight into API adoption,  usage patterns.

• Block or throttle requests that exceed their request rate limits.

• Apply different permission levels to different users.

Authenticate Service

Authentication Process

An application presents user credentials to Authenticate within an HTTP request packet.  If Authenticate accepts the credentials, its HTTP response provides a cookie and a token, used to access services requiring authentication.

• You request service by sending an HTTP request message, and the service responds with a response message.
• Your request message can provide request information in the URL, the headers and the body.
• The request and response bodies can be in your choice of formats: JSON.

Credentials

Credentials consist of information, assigned by Vitalware, which the user provides to Authenticate.

• The API key assigned by Mashery
• The Vitalware user name 
• The Vitalware user password 
• Every user name is unique over all Vitalware users and services, not just within an entity or entity hierarchy.

Authentication Methods

There are two authentication methods that you can use to authenticate a user or a proxy user: key credentials and Hash-based Message Authentication Code (HMAC).

The key credentials method provides two ways to authenticate a user:

• A user’s credentials can be used to authenticate that user to use services.
• A user’s credentials can be used to authenticate another user, a proxy user, to use services.

To use the key credentials method you provide an API key, a user name, and a password. To authenticate a proxy user, you also provide the user name for the proxy user. The key credentials method is discussed below.

The HMAC method uses a cryptographic hash function to calculate a message authentication code. Currently Vitalware supports the HMAC-SHA256 MAC algorithm, but can support others on request. Talk with your Vitalware representative if you wish to use HMAC authentication.

Note: An entity’s API key may be different in the test and production environments. 

Authentication Request Message 

Method and URI

Use the POST method for your request messages, and this URI:

https://mashery.vitalware.com/ws/v2/Auth?api_key={apikey}

Headers

You specify the request and response formats in the headers.

Request Body

In the request body you provide values for these parameters.

Here is a request body in JSON format. The verifying user and the actual user are the same.

{ "username": "yourVitalwareUserNameHere", "password": "yourVitalwarePasswordHere" }

Authentication Results

If Authenticate accepts the credentials, its HTTP response provides a cookie and a token, either of which can provide access to services that require authentication. Authenticate provides the cookie in a Set-Cookie header. If authentication occurs in a browser where cookies are allowed, the cookie is set by the browser, and is available for use by browser-based applications.

The name of the cookie is ss-id. It is for domain .vitalware.com and is a session cookie.

Authenticate places the token in the response body. It is a string value named vwToken. Here is a JSON response that returns the token:

{
  "userId": "oxtX8vyHBrs5jKvbCptB",
  "sessionId": "dgPs2Pt9vF1j2FcLuuMW",
  "username": "yourVitalwareUserNameHere",
  "meta": {
    "vwToken": "ZudQczJQdDl2RjFEjkZjTDl2TVc=",
    "timeToLive": "01:00:00",
    "sessionState": "established"
  },
  "version": "1",
  "responseStatus": {
    "deprecated": false
  }
}

The terminating “=” is part of the token and must be included when the token is used.  Once you have received a token,   the token is live for 1 hour and then times out after 1 hour of inactivity.   

Error Codes

Microsoft .NET Method

If you are using Microsoft's .NET framework, you can use WebRequest.Create to create an HttpWebRequest object.

HttpWebRequest rawRequest = (HttpWebRequest)WebRequest.Create(endpoint);
rawRequest.Method = "POST";
rawRequest.ContentLength = data.Length;
rawRequest.ContentType = @"application/json";
rawRequest.Accept = @"application/json";
rawRequest.KeepAlive = true;<span style="font-size: 12px; white-space: normal;">
</span>