Sometimes you may wish to automatically authenticate your users into Insites. This API allows you to generate single-use API tokens which are valid for 30 seconds. All requests to our API should be authenticated. Our API is RESTful and communicates using JSON.
About this API
Access to this API gives the ability to log in as any user in your Insites account.
Only use this API if you fully understand how it works and the security risks associated. You are responsible for keeping your API keys secure and ensuring this API is not abused in order to gain unauthorised access.
This API allows you to generate single-use login tokens. The common use-case for this is to enable a kind of single-sign-on, where users that are already logged into your app can be linked through to Insites and be already logged in to the Insites platform.
The authentication flow works like this:
User is already authenticated into your application
User clicks a link to go to Insites
Your back-end makes an authenticated API call to Insites to generate a token
Insites returns a single use, time limited token
You redirect the user to Insites and include the single-use token as the query parameter
jwt_token
Because this feature has the ability to log in users, the following restrictions apply:
Before you can generate any tokens, it must be explicitly activated in your Insites account (Account settings -> Auth & users -> Allow API to generate auth tokens)
You may only generate tokens for users, advanced users and administrators - you cannot generate tokens for any other types of user
The generated tokens expire after 30 seconds.
Generate a single-use login token
Method: POST
Request body should be JSON encoded, and can include the following fields:
Property | Definition | Required |
username | String – This user’s username (usually their email address) | Yes |
path | String – The app path to send the user to after the token has been generated (e.g. | No |
Example
curl "https://api.insites.com/api/v1/auth-token" --header "api-key:[YOUR API KEY]" --data "{"username":"[EMAIL]","path":"[PATH]"}"
Expected response
If successful, you would expect a 201 response, with a body containing the authentication token and a pre-assembled redirect link like this:
{
"token":"12345",
"redirect_to":"https://app.insites.com/all-reports?auth_jwt=12345",
}
All possible responses
Code | Reason |
201 | Token created. |
403 | Account does not have sufficient permissions to generate tokens. |
404 | The user could not be found, does not exist in your account or has a permission level that prohibits generation of authentication tokens. |