Impersonation

We allow our resellers to call its APIs on behalf of their customers’ accounts so that customers can be easily created with separate accounts for configuration and data protection reasons whilst still making it easy to call our APIs.

The mechanism works using a federation mechanism where your (reseller) own issued tokens are trusted and used to indicate which account is needed to be impersonated. The token must contain the account you want to impersonate and must be time limited, so you will need to generate these dynamically before making a call (or series of calls) to our APIs, but as they are self-signed on your side there is no additional round tripping required.

Creating Impersonation Tokens

The tokens you need to generate need to be JWTs (JSON Web Token) format and meet the following minimum requirements:

1. must have an issuer iss claim matching an agreed value for your reseller
2. must be signed using the agreed secret for your reseller using HMAC SHA256 algorithm
3. must have an audience aud claim of https://api.comapi.com
4. must have a resellerId claim matching the id of your reseller account as an integer
5. must have an accountId claim matching the id of the account you are trying to access as an
   integer
6. must have an expiry exp claim that is no further than 2 hours in the future based on Unix Epoch
   time (
   An example of the JSON for the token would be:

{
  "accountId": 1234,
  "resellerId": 4321,
  "exp": 1516703911,
  "aud": "https://api.comapi.com",
  "iss": "my_unique_id"
}

Please contact your account manager to register the following details to enable reseller impersonation.
Note: Reseller impersonation will not work until this registration process is complete!

• Please provide you issuer identity e.g. the value placed in the JWTs iss claim
• Please provide your secret you sign the JWTs with (Please ensure this is sent using secure communication and is at least 128 bits / 16 characters long)
• Your required permissions for accounts when impersonated

Using Impersonation Tokens

To use your impersonation token simply use it as an alternative to the JWT token in your API calls done on behalf of your customers in the Authorization HTTP header using the Bearer type e.g.:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.M4

We have created an example in C# for creating and using an impersonation token which can be found in Github here.