Zeamster docs

Authentication

Note: developer-id is required in the headers OR in the query string parameters.

1) User Id / User Api Key Method

This method is used for system integrations where typing a username/password isn’t an option. For this method, you will need to use the user_id and user_api_key values for the User account performing the request. For more information on how to set or generate a user_api_key, please take a look at the Users Endpoint documentation.

Once you have these credentials, you can use one of the following methods:

  • Request Headers: Pass your user_id and user_api_key as "user-id" and "user-api-key" in your Request Headers.
  • Query String Parameters: Pass your user_id and user_api_key as "user-id" and "user-api-key" in the URL for your request.
  • You can also use your user_id and user_api_key as your "username" and "password" to construct a Basic Authentication Header.​​​​​​​
Request Headers

Below you can see an example in Node.js where we provide the user_id and user_api_key values as request headers. 

Note: Pay close attention to the fact that when providing these values in your request, you substitute the underscore characters (_) with dashes (-). This is true for both the Request Header, and Query String Parameter methods.

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://{{host}}/v2/contacts/{{contact_id}}',
  headers: {
    'developer-id': '{{developer_id}}',
    'user-id': '{{user_id}}',
    'user-api-key': '{{user_api_key}}'
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});
Query String Parameters

Below you can see an example where we provide the user_id and user_api_key values as querystring parameters. 

Note: Pay close attention to the fact that when providing these values in your URL, you substitute the underscore characters (_) with dashes (-). This is true for both the Request Header, and Query String Parameter methods.

GET https://{{domain}}/v2/contacts?user-id={{user_id}}&user-api-key={{user_api_key}}&developer-id={{developer_id}}

2) Token Method

  1. Pass your username, password and domain in the format depicted below under "POST  /v2/token"
  2. You will get a response object as shown below under the Response tab for "POST  /v2/token"
  3. This contains the token that you can attach to your new requests in the following ways:
    • GET /v2/contacts?access-token=3pPzNQstYfXDCE5x
    • Set your “access-token” as a header
  4. The expire time is included in the response, this is 15 minutes. Every successful request will refresh your expire time back to 15, after 15 minutes of idle time your token will expire and you have to acquire a new one
  5. You can manually expire your token by doing this request: DELETE /v2/token/3pPzNQstYfXDCE5x

 

POST /v2/token

{
    "username": "myusername", //REQUIRED
    "password": "xxxxxxxx", //REQUIRED
    "domain": "xxxx.sandbox.domain.com" //REQUIRED
}
{
    "token": {
        "id": "123456789012345678901234",
        "expire": 15,
        "first_name": "John",
        "last_name": "Doe",
        "password_expire_ts": 1422283692,
        "time": 1402283692,
        "token": "abcdefghijklmnop",
        "username": "myusername",
        "primary_location_id": "123456789012345678901234",
        "timezone": "America/New_York",
        "user_type_id": 200
    }
}

 

DELETE /v2/token/{token}

{
    // Empty Payload - Nothing Needed Here
}
No JSON response provided.  Only HTTP response code.

204 - Success, Token Deleted
404 - Fail, Token Not Found

3) HMAC

This method uses the user-id, timestamp and hash-key as inputs. the hash-key can be generated by performing an sha256 hash to the concatenation of the user id and timestamp and using the User's user_hash_key as a hash,
the hash-key will expire every 15 minutes

Note: Pay close attention to the fact that when providing these values in your request, you substitute the underscore characters (_) with dashes (-). This is true for both the Request Header, and Query String Parameter methods.

these are all the endpoints that support HMAC authentication:
v2/accountform
v2/accountvaults
v2/payform
v2/routeraccountvault
v2/salestax
v2/transactions

var request = require("request");
var user_id = '{{user_id}}';
var curTime = Math. round((new Date()). getTime() / 1000);
var user_hash_key = '{{user_hash_key}}';

var hash = CryptoJS.HmacSHA256(user_id + curTime, user_hash_key);
var options = {
  method: 'GET',
  url: 'https://{{host}}/v2/contacts/{{contact_id}}',
  headers: {
    'developer-id': '{{developer_id}}',
    'user-id': user_id,
    'hash-key': hash,
    'timestamp': curTime
    
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

4) SSO (Single Sign-On)

This method allows users to authenticate by just clicking a generated url
this method is available to this endpoint
v2/contactsso

more details here: https://docs.zeamster.com/developers/quick-start/sso

 

5) OAuth

this method uses a token aquired from the OAuth authorization process
the token can then be used as bearer token for the Authorization header
this Authentcation is available on most endpoints

more in-depth information here for the whole OAuth process
https://docs.zeamster.com/developers/quick-start/oauth-authorization

var request = require("request");

var options = {
  method: 'GET',
  url: 'https://{{host}}/v2/contacts/{{contact_id}}',
  headers: {
    'developer-id': '{{developer_id}}',
    'Authorization': 'Bearer {{access-token}}',
  }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});