Visitor Authentication

Add an Authentication Provider

Action: POST /sites/{site_id}/visitor_authentication_providers

Add an authentication provider to the given site. Glia platform currently integrates with OpenID Connect providers. Note that one site can have multiple authentication providers.

The body of the request must include the following parameters:

Parameter

Required

Type

Description

name

Yes

String

Descriptive name.

type

Yes

String

Type of the authentication provider. Supported values are openid_connect and oauth2.

authorize_url

Yes

String

The URL where Glia directs the visitor to authenticate, determined by the authentication provider.

access_token_url

Yes

String

The URL from where Glia will fetch the ID and/or access tokens, determined by the authentication

userinfo_url

No

String

The URL from where Glia will fetch user information from, determined by the authentication provider. Used only when type is oauth2. When type is openid_connect you find the same data within the ID token received via access_token_url. Glia will request the URL from the authentication provider via HTTP GET method that contains Authorization: Bearer access_token and Accept: application/json headers, where access_token was retrieved from access_token_url beforehand. The response should contain any or none of the following fields (other fields are ignored): name, email, preferred_username. See below for an example userinfo_url response.

scope

Yes

String

Determines which visitor’s details (e.g. name, email) are retrieved in ID token and/or what permissions are granted by the access token. In case of OpenID Connect, the scope must include at least openid; email and profile (separated by space) should be added to receive visitor attributes. See openid.net for details.

client_id

Yes

String

The client ID that Glia uses when fetching the ID and/or access tokens from the authentication

client_secret

Yes

String

The client secret that goes with the client ID above.

default_provider

Yes

Boolean

true if the added authentication provider should be the default one, false otherwise. There can be only one default provider for each site.

cURL
JavaScript
Ruby
cURL
curl --request POST \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--header "Content-Type: application/json" \
--data-binary '{
"name":"Authentication provider settings for example.com",
"type":"openid_connect",
"authorize_url":"https://example.com/oauth2/v1/authorize",
"access_token_url":"https://example.com/oauth2/v1/token",
"scope":"openid%20email%20profile",
"client_id": $client_id,
"client_secret": $client_secret,
"default_provider":true
}' \
"https://api.salemove.com/sites/$site_id/visitor_authentication_providers"
JavaScript
const XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
const xhr = new XMLHttpRequest();
xhr.open(
'POST',
`https://api.salemove.com/sites/${siteId}/visitor_authentication_providers`,
false
);
xhr.setRequestHeader('authorization', `Bearer ${accessToken}`);
xhr.setRequestHeader('accept', 'application/vnd.salemove.v1+json');
xhr.setRequestHeader('Content-Type', 'application/json;charset=UTF-8');
const authenticationProviderSettings = {
name: 'Authentication provider settings for example.com',
type: 'openid_connect',
authorize_url: 'https://example.com.com/oauth2/v1/authorize',
access_token_url: 'https://example.com.com/oauth2/v1/token',
scope: 'openid%20email%20profile',
client_id: '0aaa00aaaa0a0aaa00a0',
client_secret: 'zZzZzzZzZzzZZzZ0zZzZzzZzZzzZZzZ0'
};
xhr.send(JSON.stringify(authenticationProviderSettings));
const response = JSON.parse(xhr.responseText);
console.log(response);
Ruby
require 'httparty'
access_token = ARGV[0].strip
site_id = ARGV[1].strip
headers = {
Authorization: "Bearer #{access_token}",
Accept: 'application/vnd.salemove.v1+json',
'Content-Type' => 'application/json'
}
authentication_provider_settings = {
name: 'Authentication provider settings for example.com',
type: 'openid_connect',
authorize_url: 'https://example.com.com/oauth2/v1/authorize',
access_token_url: 'https://example.com.com/oauth2/v1/token',
scope: 'openid%20email%20profile',
client_id: '0aaa00aaaa0a0aaa00a0',
client_secret: 'zZzZzzZzZzzZZzZ0zZzZzzZzZzzZZzZ0'
}
ENDPOINT = "https://api.salemove.com/sites/#{site_id}/visitor_authentication_providers"
raw_response = HTTParty.post("#{ENDPOINT}",
body: authentication_provider_settings,
headers: headers
)
response = JSON.parse raw_response.body
puts response

Generates the output

{
"id": "c892ce61-ec63-4428-aade-3124ec602588",
"site_id": "3b88576f-1fb2-4aa5-9188-2931df5a0783",
"name": "Authentication provider settings for example.com",
"type": "openid_connect",
"authorize_url": "https://example.com.com/oauth2/v1/authorize",
"access_token_url": "https://example.com.com/oauth2/v1/token",
"scope": "openid%20email%20profile",
"default_provider": true,
"client_id": "0oan31sqxd7s1gkg30x7",
"created_at": "2019-11-20T01:32:38Z",
"created_by": "c0a7f32f-6806-4045-92bd-33c04b50e883",
"updated_at": "2019-11-20T01:32:38Z",
"updated_by": "c0a7f32f-6806-4045-92bd-33c04b50e883"
}

Example userinfo_url Response

{
"name": "John Smith",
"email": "john.smith@example"
}

Update an Authentication Provider

Action: PATCH /sites/{site_id}/visitor_authentication_providers/{provider_id}

Update the given authentication provider.

cURL
JavaScript
Ruby
cURL
curl --request PATCH \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
--header "Content-Type: application/json" \
--data-binary '{
"name":"Updated authentication provider settings for example.com",
"type":"openid_connect",
"authorize_url":"https://example.com/oauth2/v1/authorize",
"access_token_url":"https://example.com/oauth2/v1/token",
"scope":"openid%20email%20profile",
"client_id": $client_id,
"client_secret": $client_secret,
"default_provider":false
}' \
"https://api.salemove.com/sites/$site_id/visitor_authentication_providers/$provider_id"
JavaScript
const XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
const xhr = new XMLHttpRequest();
xhr.open(
'PATCH',
`https://api.salemove.com/sites/${siteId}/visitor_authentication_providers`,
false
);
xhr.setRequestHeader('authorization', `Bearer ${accessToken}`);
xhr.setRequestHeader('accept', 'application/vnd.salemove.v1+json');
xhr.setRequestHeader('Content-Type', 'application/json;charset=UTF-8');
const authenticationProviderSettings = {
name: 'Authentication provider settings for example.com',
type: 'openid_connect',
authorize_url: 'https://example.com.com/oauth2/v1/authorize',
access_token_url: 'https://example.com.com/oauth2/v1/token',
scope: 'openid%20email%20profile',
client_id: '0aaa00aaaa0a0aaa00a0',
client_secret: 'zZzZzzZzZzzZZzZ0zZzZzzZzZzzZZzZ0'
};
xhr.send(JSON.stringify(authenticationProviderSettings));
const response = JSON.parse(xhr.responseText);
console.log(response);
Ruby
require 'httparty'
access_token = ARGV[0].strip
site_id = ARGV[1].strip
headers = {
Authorization: "Bearer #{access_token}",
Accept: 'application/vnd.salemove.v1+json',
'Content-Type' => 'application/json'
}
authentication_provider_settings = {
name: 'Authentication provider settings for example.com',
type: 'openid_connect',
authorize_url: 'https://example.com.com/oauth2/v1/authorize',
access_token_url: 'https://example.com.com/oauth2/v1/token',
scope: 'openid%20email%20profile',
client_id: '0aaa00aaaa0a0aaa00a0',
client_secret: 'zZzZzzZzZzzZZzZ0zZzZzzZzZzzZZzZ0'
}
ENDPOINT = "https://api.salemove.com/sites/#{site_id}/visitor_authentication_providers"
raw_response = HTTParty.patch("#{ENDPOINT}",
body: authentication_provider_settings,
headers: headers
)
response = JSON.parse raw_response.body
puts response

Generates the output

{
"id": "c892ce61-ec63-4428-aade-3124ec602588",
"site_id": "3b88576f-1fb2-4aa5-9188-2931df5a0783",
"name": "Updated authentication provider settings for example.com",
"type": "openid_connect",
"authorize_url": "https://example.com.com/oauth2/v1/authorize",
"access_token_url": "https://example.com.com/oauth2/v1/token",
"scope": "openid%20email%20profile",
"default_provider": false,
"client_id": "0oan31sqxd7s1gkg30x7",
"created_at": "2019-11-20T01:32:38Z",
"created_by": "c0a7f32f-6806-4045-92bd-33c04b50e883",
"updated_at": "2019-11-20T01:32:38Z",
"updated_by": "c0a7f32f-6806-4045-92bd-33c04b50e883"
}

Get Authentication Providers

Action: GET /sites/{site_id}/visitor_authentication_providers

Get the list of the authentication providers added to the given site.

cURL
JavaScript
Ruby
cURL
curl --request GET \
--header "Authorization: Bearer $access_token" \
--header "Accept: application/vnd.salemove.v1+json" \
https://api.salemove.com/sites/$site_id/visitor_authentication_providers
JavaScript
const XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
const xhr = new XMLHttpRequest();
xhr.open(
'GET',
`https://api.salemove.com/sites/${siteId}/visitor_authentication_providers`,
false
);
xhr.setRequestHeader('authorization', `Bearer ${accessToken}`);
xhr.setRequestHeader('accept', 'application/vnd.salemove.v1+json');
xhr.send();
const response = JSON.parse(xhr.responseText);
console.log(response);
Ruby
require 'httparty'
access_token = ARGV[0].strip
site_id = ARGV[1].strip
headers = {
Authorization: "Bearer #{access_token}",
Accept: 'application/vnd.salemove.v1+json'
}
ENDPOINT = "https://api.salemove.com/sites/#{site_id}/visitor_authentication_providers"
raw_response = HTTParty.get("#{ENDPOINT}",
headers: headers
)
response = JSON.parse raw_response.body
puts response

Generates the output

[
{
"id": "4bfa559f-0e22-43b2-935b-af3d627c0a85",
"site_id": "3b88576f-1fb2-4aa5-9188-2931df5a0783",
"name": "Authentication provider settings for example.com",
"type": "openid_connect",
"authorize_url": "https://example.com/authorize_url",
"access_token_url": "https://example.com/access_token_url",
"scope": "openid%20email%20profile",
"default_provider": true,
"client_id": "123456",
"created_at": "2019-11-15T07:16:55Z",
"created_by": "c0a7f32f-6806-4045-92bd-33c04b50e883",
"updated_at": "2019-11-15T07:16:55Z",
"updated_by": "c0a7f32f-6806-4045-92bd-33c04b50e883"
},
{
"id": "c892ce61-ec63-4428-aade-3124ec602588",
"site_id": "3b88576f-1fb2-4aa5-9188-2931df5a0783",
"name": "Updated authentication provider settings for example2.com",
"type": "openid_connect",
"authorize_url": "https://example2.com.com/oauth2/v1/authorize",
"access_token_url": "https://example2.com.com/oauth2/v1/token",
"scope": "openid%20email%20profile",
"default_provider": false,
"client_id": "0oan31sqxd7s1gkg30x7",
"created_at": "2019-11-20T01:32:38Z",
"created_by": "c0a7f32f-6806-4045-92bd-33c04b50e883",
"updated_at": "2019-11-21T01:32:38Z",
"updated_by": "c0a7f32f-6806-4045-92bd-33c04b50e883"
}
]

Create an Authentication Request

Action: POST /visitor_authentication_requests

In order to authenticate the visitor using an authentication provider, an authentication request must be created. Note that in addition to this REST API endpoint, there is an authentication request message that can be used to request authentication from a bot and the Visitor JS SDK has a method createAuthenticationRequest to request authentication from visitor side.

The body of the request must include the following parameters:

Parameter

Required

Type

Description

site_id

Yes

String

The ID of the site to which authentication request will be created.

visitor_id

Yes

String

The ID of the visitor to whom authentication request will be created.

authentication_provider_id

Yes

String

The ID of the authentication provider to be used.

webhooks

No

Array

Array of webhook objects described in HTTP Webhooks. Allowed events are: visitor.authentication.success and visitor.authentication.failure, see details in Webhooks.

"webhooks": [
{
"url": "http://www.example.com/webhook/success",
"events": ["visitor.authentication.success"]
},
{
"url": "http://www.example.com/webhook/failure",
"events": ["visitor.authentication.failure"]
},
{
"url": "http://www.example.com/webhook/log",
"events": [
"visitor.authentication.success",
"visitor.authentication.failure"
]
}
]
cURL
JavaScript
Ruby
cURL
curl --request POST \
--header "Authorization: Bearer $access_token" \
--header "Content-Type: application/json" \
--header "Accept: application/vnd.salemove.v1+json" \
--data-binary '{
"site_id": "10b08a06-4e22-431d-a85c-c8c9b61fb8d4",
"visitor_id": "1772097b-5f24-4b75-84af-de87ca87e168",
"authentication_provider_id": "02d7aaf2-966e-4292-9102-4afcc20397f3",
"webhooks": [
{
"url": "http://www.example.com/webhook/success",
"events": ["visitor.authentication.success"]
},
{
"url": "http://www.example.com/webhook/failure",
"events": ["visitor.authentication.failure"]
}
]
}' \
"https://api.salemove.com/visitor_authentication_requests"
JavaScript
const XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
const xhr = new XMLHttpRequest();
xhr.open('POST',`https://api.salemove.com/visitor_authentication_requests`,false);
xhr.setRequestHeader('authorization', `Bearer ${accessToken}`);
xhr.setRequestHeader('accept','application/vnd.salemove.v1+json');
xhr.setRequestHeader("Content-Type", "application/json;charset=UTF-8");
const authenticationRequest = {
"site_id": "10b08a06-4e22-431d-a85c-c8c9b61fb8d4",
"visitor_id": "1772097b-5f24-4b75-84af-de87ca87e168",
"authentication_provider_id": "02d7aaf2-966e-4292-9102-4afcc20397f3",
"webhooks": {
{
"url": "http://www.example.com/webhook/success",
"events": ["visitor.authentication.success"]
},
{
"url": "http://www.example.com/webhook/failure",
"events": ["visitor.authentication.failure"]
}
}
};
xhr.send(JSON.stringify(authenticationRequest));
const response = JSON.parse(xhr.responseText);
console.log(response);
Ruby
require 'httparty'
access_token = ARGV[0].strip
site_id = ARGV[1].strip
headers = {
Authorization: "Bearer #{access_token}",
Accept: 'application/vnd.salemove.v1+json',
'Content-Type' => 'application/json'
}
authentication_request = {
site_id: "10b08a06-4e22-431d-a85c-c8c9b61fb8d4",
visitor_id: "1772097b-5f24-4b75-84af-de87ca87e168",
authentication_provider_id: "02d7aaf2-966e-4292-9102-4afcc20397f3",
webhooks: {
{
url: "http://www.example.com/webhook/success",
events: ["visitor.authentication.success"]
},
{
url: "http://www.example.com/webhook/failure",
events: ["visitor.authentication.failure"]
}
}
}
ENDPOINT = "https://api.salemove.com/visitor_authentication_requests"
raw_response = HTTParty.post("#{ENDPOINT}",
body: authentication_request,
headers: headers
)
response = JSON.parse raw_response.body
puts response

Generates the output

{
"authentication_request_id": "4bfa559f-0e22-43b2-935b-af3d627c0a85"
}

Close an Authentication Request

Action: DELETE /visitor_authentication_requests/{authentication_request_id}

Closes an on-going authentication request for a specific visitor user on a specific site.

The body of the request must include the following parameters:

Parameter

Required

Type

Description

site_id

Yes

String

The ID of the site to which the given authentication request belongs to.

visitor_id

Yes

String

The ID of the visitor whose authentication request will be closed.

fail_reason

Yes

String

The reason why the authentication request is closed. Can be any string to clearly indicate the reason: a human-readable explanation, error code, etc.

cURL
JavaScript
Ruby
cURL
curl --request DELETE \
--header "Authorization: Bearer $access_token" \
--header "Content-Type: application/json" \
--header "Accept: application/vnd.salemove.v1+json" \
--data-binary '{
"site_id":"3b88576f-1fb2-4aa5-9188-2931df5a0783",
"visitor_id":"3b757312-483f-41a2-8e22-ec0296c434d8",
"fail_reason":"Reason why the authentication request has been closed"
}' \
"https://api.salemove.com/visitor_authentication_requests/33f268c6-6a80-4430-95a8-44e1dd854053"
JavaScript
const XMLHttpRequest = require('xmlhttprequest').XMLHttpRequest;
const xhr = new XMLHttpRequest();
xhr.open(
'DELETE',
`https://api.salemove.com/visitor_authentication_requests/33f268c6-6a80-4430-95a8-44e1dd854053`,
false
);
xhr.setRequestHeader('authorization', `Bearer ${accessToken}`);
xhr.setRequestHeader('accept', 'application/vnd.salemove.v1+json');
xhr.setRequestHeader('Content-Type', 'application/json;charset=UTF-8');
const authenticationRequest = {
site_id: '3b88576f-1fb2-4aa5-9188-2931df5a0783',
visitor_id: '3b757312-483f-41a2-8e22-ec0296c434d8',
fail_reason: 'Reason why the authentication request has been closed'
};
xhr.send(JSON.stringify(authenticationRequest));
const response = JSON.parse(xhr.responseText);
console.log(response);
Ruby
require 'httparty'
access_token = ARGV[0].strip
site_id = ARGV[1].strip
headers = {
Authorization: "Bearer #{access_token}",
Accept: 'application/vnd.salemove.v1+json',
'Content-Type' => 'application/json'
}
authentication_request = {
"site_id":"3b88576f-1fb2-4aa5-9188-2931df5a0783",
"visitor_id":"3b757312-483f-41a2-8e22-ec0296c434d8",
"fail_reason":"Reason why the authentication request has been closed"
}
ENDPOINT = "https://api.salemove.com/visitor_authentication_requests/33f268c6-6a80-4430-95a8-44e1dd854053"
raw_response = HTTParty.delete("#{ENDPOINT}",
body: authentication_request,
headers: headers
)
response = JSON.parse raw_response.body
puts response