The InstantKB Web API User Key



To make authenticated requests into the InstantKB Web API you must provide both a valid application key and a valid user key within the "Authorization" header for your request. In this article we'll detail how you obtain a users API key both via the InstantKB web interface and programmatically via the InstantKB Web API.

User API Keys

To perform actions via the InstantKB Web API on behalf of a specific user you'll need to provide the users API key within your request. By default remote API access is disabled for all user accounts within InstantKB.

To enable remote API access for a specific user account and obtain the users  unique API key you'll need to visit the InstantKB Administrator Control Panel > Users > Manage Users page. From the Manage Users page you'll need to edit the desired user account you wish to make request on behalf of and enable remote API access as shown below...


Once you've enabled API access you can see the users unique API key which you'll need to use within the "Authorization" header for your request as shown below...

Administrator & Agent API Keys

To perform actions via the InstantKB Web API that require administrator or support agent privileges you must provide a valid user key for an existing administrator or support agent within InstantKB. To enable API access for a specific administrator or support agent you'll simply need to provide the administrator or support agents user API key within your request. You can manage an administrators or support agents API key similar to regular users as demonstrated above.

Obtaining a User Key Programmatically

To obtain a users API key programmatically you can call the "api/login" endpoint and pass in a valid email address and password for an existing InstantKB user account.

You must supply a valid Application Key when calling the "api/login" endpoint. You can see an example of this request below...

POST api/login HTTP/1.1
Host: https://demos.instantasp.co.uk/InstantKB2018/
Authorization: Basic FoMEfIWA3eykhATmFuUt0C01SUzuFgRccT82BTYd26vv6npoiD273LgQVw0kyJ1VGQY4JjG5iEo
Content-Type: application/json
X-Api-Version: 1


data: "{\nusername: \"admin@admin.com\",\npassword: \"admin\"\n}"

IMPORTANT
As user credentials are being passed over the wire we would strongly suggest using an secure SSL connection when posting to the api/login endpoint.

If valid user credentials are provided you'll receive the users API key within the response as shown below...


"user_id": 1
"user_key": "k3JRgM3Swm1Hb7dTSHXKBoeEIxwdP6mqPDxa5rMdDSVjCKGqaTDBU1ai4wWF3w57ncAunJfbY7tTMrK2LAOf57KCbZoPUHaarzva29NSFuoVRQKaofJwLHTdcFhV3a4HmAy4Zw02B16vcT2DyQmZE5o3zwVsFMxGKSQlnYMJ6rcbtU8MyCRs3LfaxRLv9v"
}

You can then store and use the users key for subsequent requests into the InstantKB Web API on behalf of that user to avoid storing or persisting the users InstantKB account credentials within your application.