API Authentication

All calls to the REST service must be authenticated by using one of the following:

  • JSON Web Token

  • API Keys

JSON Web Token

Tokens can be generated via a POST to the token service using an appropriate username and password.

     Note: JSON Web Tokens inherit roles from the user used to generate them. Ensure you generate tokens with a user that has the appropriate Permissions to access the required objects.

POST http://<host>:<port>/1Integrate/rest/token
{"username":"user1", "password":"password1"}

This will return an Authorization header:

Authorization: eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiIxU3BhdGlhbCIsImV4cCI6MTUwMTI1Mjk4OCwianRpIjoiSjRXcGNYZVNtQzJ3aFVZMU9femhhdyIsImlhdCI6MTUwMTI0NTc4OCwic3ViIjoiMVNwYXRpYWwiLCJyb2xlcyI6WyJyc19hZG1pbnMiLCJyc191c2VycyIsInJzd3N1c2VyIl0sInJlbWVtYmVyIjpudWxsfQ.foy1N1kCuQjk7zjgcqilJoxQxp6DQsO3FYrJs8Le79wQ3JPE6onTmz_X6DQxfjVyL9r9SSIgfPxzTrUt-04PQFvbjsVr_pbCBhLYaDr_luTnzQ0OrVZJEt9Avy2gRgvGmYhVycKOHpn0ZVQKwZAt_hJLkLUczsUR2AulxCYxITDotXte3j5Vy7ZhQRcJ4Eq-VNtSlRy6kYzlNAF-F_JpgEh5RNCDKIxyvbZj1R4jJSBWX_mOT7_coFuqpSyyTZcUfUvCo5NqFEZ-y0sXHzEVwSHxA24iyiJHg_U7NE9weEtcGgKzLI7vZgkxEJ8oNxw5VSxvbNNtEMlAtBcMf-9bBA

Any API calls must have an Authorization entry in the header with the value of 'Bearer', followed by a space, followed by the token returned in the Authorization header of the call to the token service, as in the following example:

Authorization: Bearer eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiIxU3BhdGlhbCIsImV4cCI6MTUwMTI1Mjk4OCwianRpIjoiSjRXcGNYZVNtQzJ3aFVZMU9femhhdyIsImlhdCI6MTUwMTI0NTc4OCwic3ViIjoiMVNwYXRpYWwiLCJyb2xlcyI6WyJyc19hZG1pbnMiLCJyc191c2VycyIsInJzd3N1c2VyIl0sInJlbWVtYmVyIjpudWxsfQ.foy1N1kCuQjk7zjgcqilJoxQxp6DQsO3FYrJs8Le79wQ3JPE6onTmz_X6DQxfjVyL9r9SSIgfPxzTrUt-04PQFvbjsVr_pbCBhLYaDr_luTnzQ0OrVZJEt9Avy2gRgvGmYhVycKOHpn0ZVQKwZAt_hJLkLUczsUR2AulxCYxITDotXte3j5Vy7ZhQRcJ4Eq-VNtSlRy6kYzlNAF-F_JpgEh5RNCDKIxyvbZj1R4jJSBWX_mOT7_coFuqpSyyTZcUfUvCo5NqFEZ-y0sXHzEVwSHxA24iyiJHg_U7NE9weEtcGgKzLI7vZgkxEJ8oNxw5VSxvbNNtEMlAtBcMf-9bBA

The token needs to be added to the header with a 'Bearer' keyword:

Example Python Script
url = 'http://<host>:<port>/1Integrate/rest/%s'
tokenResponse = requests.post(url % 'token', json=
{'username':'<user>','password': '<password>'})
tokenResponse.raise_for_status()
token = 'Bearer ' + tokenResponse.headers['Authorization']
#Create a requests session to avoid having to specify headers on each call.
requestSession = requests.Session()
requestSession.headers.update( {'Authorization': token, 'Accept': 'Application/JSON', 
'Content-Type': 'Application/JSON'}
)
Example PowerShell Script
$Body = '{"username":"'+$Username+'", "password":"'+$Password+'"}'
$Response = Invoke-WebRequest -Uri 'http://<host>:<port>/1Integrate/rest/token' -Method Post -Body $Body
# Read the token from the header
$Token = $Response.Headers.Authorization
# Now use the token returned in the header when sending requests
# Note, need to add 'Bearer ' before the token in the authorization header
$Headers = @{}
$Headers.Add("Authorization", "Bearer " + $Token)
Example Go Script
url := "http://<host>:<port>/1Integrate/rest/%s"

	var payload = []byte(`{
		"username": "<username>",
		"password": "<password>"
	}`)
	
	req, err := http.NewRequest("POST", fmt.Sprintf(url, "token"), bytes.NewBuffer(payload))
	if err != nil {
		// Handle the error
	}
	req.Header.Set("Content-Type", "application/json")
	
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		// Handle the error
	}
	defer resp.Body.Close()
	
	tokenHeader := "Bearer " + resp.Header.Get("Authorization")

	//create another request and provide the token in the authorization header
	otherReq, err := http.NewRequest("GET", fmt.Sprintf(url, "sessions"), bytes.NewBuffer(payload))
	if err != nil {
		// Handle the error
	}
			otherReq.Header.Set("Authorization", tokenHeader)
Example Rust Script
let base_url = "http://<host>:<port>/1Integrate/rest/";

    let payload ="{\"username\": \"<username>\",\"password\": \"<password>\"}";
    let client = reqwest::Client::new();
    let res = client.post(base_url.to_owned() + "token")
        .header(CONTENT_TYPE, "application/json")
        .body(payload)
        .send()
        .await.unwrap();
    let token_header = format!("Bearer {}", res.headers().get("Authorization").unwrap().to_str().unwrap());

    //create another request and provide the token in the authorization header
    let res = client.get(base_url.to_owned() + "sessions")
        .header(ACCEPT, "application/json")
        .header(AUTHORIZATION, token_header)
        .send()
		.await.unwrap();

Token Refresh

By default the token will last 2 hours. When you use a token to access the 1Integrate REST API and the server detects that your token is about to expire, it will refresh your token and send the new token back with the response, again in the Authorization response header.

If a longer lasting token is required, a 2 week duration token can be created using the following request:

POST http://<host>:<port>/1Integrate/rest/token?rememberMe=true

API Keys

API Keys can be generated and managed from inside the 1Integrate user interface.

API Keys take the form:

186NToBCCR21nEheTcgjuvtN1/U=7mapr4KAb5k4BBzMStiIeQ==

     Note: Ensure that the API key you are using was generated with the relevant roles to access the required objects.

To use a key to authenticate your REST calls, include an x-api-key header with the API key as its value, e.g.:

Example
PUT http://<host>:<port>/1Integrate/rest/datastores/test
x-api-key: 186NToBCCR21nEheTcgjuvtN1/U=7mapr4KAb5k4BBzMStiIeQ==
Content-Type: application/json
{ "name" :  "test" }

     Note: If a key has been revoked you will receive a 401 status code back with the error message "Key revoked". Any calls performed using deleted keys will also fail.