User Sessions

Before you execute any requests to the Cantara server, you must first establish a login session by executing the following request:

XML

URL: http(s)://[hostname]:[port]/[context]/service/[version]/server/login/[environment] 
Request-Method: POST

Where environment refers to the Cantara Access Server environment you are trying to log into. For example, E1DEV. You would have previously configured this value when you set up your environment. Refer to the Managing Environments topic for more information.

You can obtain a list of configured environments by using the console to Search for an Environment.

The login service expects a payload with the three parameters (Function Request) 'username', 'password' and 'application'. The username and password should be the credentials of a valid JDE user that can log into the environment you are trying to connect to. The application name should be a unique name for the application or client that is connecting to the Cantara Access Server.

From version 5.0 there are three additional parameters that much also be passed into every rest call:
'tenantId', 'apiKey', 'cantaraVersion'. These parameters are requirements of the cloud platform to identify the correct customer. The Tenant ID and API Key can be retrieved from the customer portal.

Once the request has been successfully executed, a response is returned. If the login is successful, information about the logged in user will be provided as defined in the JDE environment. If the login fails, the message payload contains the corresponding error. Included in the response is a login token which can be used to re-establish an expired session. In the case where you wish to use the token you would submit this in a parameter named token in replacement of the password parameter. This enables you to provide blind login functionality from a client without having to securely store the user's password within the client application.

Warning:

User sessions expire after a timeout period that is defined by the session expiry on the Java application server instance that the Cantara Access Server is deployed on. Once the timeout period has been reached, your application must reestablish the session with Cantara by consuming the login service again. You can choose to either resubmit the users login credentials or make use of the login token if it is enable on the server.

Login request and response

Endpoint: https://us.cantara.cloud/cantara/service/50/server/login/E1TEST

Request-Method: POST

Content-Type: application/json

On This Page

Login with Password Request Payload

JS

{
	"Parameter":[
		{
			"value":"JCITIZEN",
			"name":"username"
		},
		{
			"value":"MyPassword",
			"name":"password"
		},
		{
			"value":"Demo",
			"name":"application"
		}
	],
	"name":"Login",
    "tenantId": "123456",
	"apiKey": "AAA000-0000-0000-AAAA-A0A0A0A0A0",
	"cantaraVersion":"5.0"
}

Login with Token Request Payload

JS

{
	"Parameter":[
		{
			"value":"JCITIZEN",
			"name":"username"
		},
		{
			"name":"token",
			"value":"3d1b9c32f069b7717d30973f44c6620e4dfbe3d99fdd5cc2915f4536b971d734"
		},
		{
			"value":"Demo",
			"name":"application"
		}
	],
	"name":"Login",
    "tenantId": "123456",
	"apiKey": "AAA000-0000-0000-AAAA-A0A0A0A0A0",
	"cantaraVersion":"5.0"
}

Response Payload

JS

{
	"Parameter": [
		{
			"value": "FTP",
			"name": "mediaAccessMethod"
		},
		{
			"value": "JCITIZEN",
			"name": "username"
		},
		{
			"value": "1001",
			"name": "addressNo"
		},
		{
			"value": "John Citizen",
			"name": "addressNoAlphaName"
		},
		{
			"value": "",
			"name": "jobQueue"
		},
		{
			"value": "100001",
			"name": "branch"
		},
		{
			"value": "100001",
			"name": "branchAddressNo"
		},
		{
			"value": "00100",
			"name": "branchCompany"
		},
		{
			"value": "  ",
			"name": "branchCostCenterType"
		},
		{
			"value": "Rinami Distribution Centre",
			"name": "branchDescription"
		},
		{
			"value": "",
			"name": "approvalRouteCode"
		},
		{
			"value": "DME",
			"name": "dateFormat"
		},
		{
			"value": " ",
			"name": "dateSeparator"
		},
		{
			"value": " ",
			"name": "decimalCharacter"
		},
		{
			"value": "  ",
			"name": "timeZone"
		},
		{
			"value": "System Value",
			"name": "timeZoneDescription"
		},
		{
			"value": "",
			"name": "timeZoneDescription2"
		},
		{
			"value": "",
			"name": "timeZoneSpecialHandling"
		},
		{
			"value": "  ",
			"name": "timeFormat"
		},
		{
			"value": "",
			"name": "daylightRule"
		},
		{
			"value": "3d1b9c32f069b7717d30973f44c6620e4dfbe3d99fdd5cc2915f4536b971d734",
			"name": "token"
		}
	],
	"Message": {
		"value": "Transaction Successful",
		"type": 0,
		"sessionId": "6803.1200247068.20",
		"cantaraSid": "82709e6d-211f-4a3f-9b1d-89c9f00b0d7a"
	},
	"name": "Login"
}