Authentication

The eHive API uses a authentication protocol based on the OAuth 2.0 framework specification to secure incoming requests from clients. Before you can access the API you must first create a set of API Keys in your eHive account, if you don’t already have an account with us you can follow these simple instructions on how to sign up for an eHive account. Once you have a set of API Keys you will then use them during authorization and authentication.

API Keys

These are a set of three alphanumeric codes that are used when interacting with the eHive API. They can be generated by navigating to the Edit My Profile > API Keys page when signed into your eHive account. The API Keys include a:

  1. clientId – A unique code that identifies a client when it sends a request to the eHive API. This is used as part of the OAuth 2.0 authorization credentials.
  1. clientSecret – A unique code that is used during the client authorization process. It is used as part of the OAuth 2.0 authorization credentials when requesting an access grant.
  1. trackingId – A unique code that is used to track a users access in eHive. This is used to analyse users usage of eHive so that we can provide a better service and also prevent any abuse of the API.

Authorization and Authentication

We define the roles of authorization and authentication as two distinct security procedures. The authorization process is designed to identify the client as an active eHive account owner whereas the authentication process is designed to ensure that the requester is known to eHive.

During the authorization process the client sends their authorization credentials to the authorization endpoint. If the credentials are valid an access grant is issued. The access grant is used to obtain an OAuth access token from the token endpoint.

The authentication process occurs when a client sends a request to one of the eHive API methods. In the headers of the client’s request they must include the clientId and OAuth access token in order to be authenticated. If the clientId and OAuth access token are valid then the user is authenticated and their request is processed.

Authorization Credentials

A pair of unique keys that are used to authorize clients trying to access the eHive API. The authorization credentials are made up of a client identifier (clientId) and a client secret (clientSecret) and are sent to the authorization server as the first step in obtaining and OAuth token. These are included in the API keys you create in your eHive account.

Authorization Endpoint

The authorization endpoint is the URL to which authorization requests are sent. The authorization endpoint for the eHive API is: https://ehive.com/api/oauth2/v2/authorize

Access Grant

An access grant is issued by the authorization server following successfully authorizing a client’s authorization credentials. The authorization server returns a HTTP 303 (See Other) redirect response with the URI of the token endpoint and the access grant. The user then sends the access grant to the token endpoint so it can obtain an  OAuth access token.

Token Endpoint

The token endpoint is the URL to which acecss token requests are sent. The token endpoint for the eHive API is: https://ehive.com/api/oauth2/v2/token

OAuth Token

An OAuth token is an access token which is sent along with a user’s clientId for any request to an eHive API method. The OAuth token is valid for a fixed length of time before it expires and the client has to request a new one from the authorization server. The eHive API will return a HTTP 401 (Unauthorized) error if the OAuth token has expired

Authentication Flow

Here is a diagram to show the main request – response flows for each of the authorization and authentication process for the eHive API. Flow 1 shows the Authorization process and Flow 2 shows the authentication process:

 

 

Authorization Process

Step 1:

The client sends a HTTP POST request to the authorization endpoint (https://ehive.com/api/oauth2/v2/authorize) including the authorization credentials, Grant Type and Authorization type in the header section:

POST /api/oauth2/v2/authorize HTTP/1.1
Host: ehive.com
Content-Type: application/x-www-form-urlencoded
Client-Id: <your clientId>
Client-Secret: <your clientSecret>
Authorization: OAuth
Grant-Type: client_credentials

cURL example:

curl 
-v 
-H "Content-Type: application/x-www-form-urlencoded" 
-H "Client-Id: <your clientId>" 
-H "Client-Secret: <your clientSecret>" 
-H "Authorization: OAuth" 
-H "Grant-Type: client_credentials" 
-X POST https://ehive.com/api/oauth2/v2/authorize

Step 2:

An access grant is returned in a HTTP 303 (See Other) response header along with other headers required for the next step:

HTTP/1.1 303 See Other
Content-Type: application/x-www-form-urlencoded
Connection: keep-alive
Location: /api/oauth2/v2/token
Grant-Type: authorization_code
Client-Id: <your clientId>
Authorization: OAuth
Access-Grant: <access grant>

Step 3:

Once the access grant is received a HTTP GET request is sent to the token endpoint (https://ehive.com/api/oauth2/v2/token) with the following header values received from the authorization server in Step 2:

GET /api/oauth2/v2/token HTTP/1.1
Host: ehive.com
Content-Type: application/x-www-form-urlencoded
Client-Id: <your clientId>
Access-Grant: <access grant>
Connection: keep-alive
Authorization: OAuth
Grant-Type: authorization_code

cURL Example:

curl 
-v 
-H "Content-Type: application/x-www-form-urlencoded" 
-H "Client-Id: " 
-H "Access-Grant: " 
-H "Connection: keep-alive" 
-H "Authorization: OAuth" 
-H "Grant-Type: authorization_code" 
-X GET https://ehive.com/api/oauth2/v2/token

Step 4:

Assuming you have passed all of the correct header information into the previous step you will receive your OAuth access token as a JSON response. In this response the grantType refers to you eHive grant type rather then your OAuth Grant-Type header. For version 2 of the API this value will always be “API”:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "clientId" : "<your clientId>",
    "oauthToken" : "<new OAuth access token>",
    "grantType" : "API"
}

Authentication Process

Step 1:

You must include your OAuth access token and clientId in every request you send to an eHive API method. Your request must also include your trackingId in the request’s query string:

GET /api/v2/accounts/3406?trackingId=<your trackingId> HTTP/1.1
Host: ehive.com
Client-Id: <your clientId>
Authorization: Basic <your OAuth access token>
Grant-Type: authorization_code

cURL Example:

curl 
-v 
-H "Client-Id: <your clientId>" 
-H "Authorization: Basic <your OAuth access token>" 
-H "Grant-Type: authorization_code" 
-X GET https://ehive.com/api/v2/accounts/3406?trackingId=<your trackingId>

Step 2:

Provided your authentication credentials are correct and your request URI is valid then you should get a JSON domain object containing the eHive data you requested.