login

Availability

Breeze 4 and Breeze 5; Connect Enterprise Web Services 6

Description

Logs a user in to Enterprise Server or an Enterprise Hosted account.

In a client application, after logging in a user, you must read and store the cookie called BREEZESESSION, which can be found in the HTTP headers of the response from login. You must then include the value of that cookie in every subsequent request that you make for that user.

If you cannot retrieve cookie values from HTTP response headers, you can call common-info to get the cookie value before the user logs in. Then, pass the value to login using the session request parameter:

https://example.com/api/xml?action=login&login=loginId&password=password
        &session=value

You can also use the session parameter on any API call you make after login. For example, to call principal-list after logging in, you can enter:

https://example.com/api/xml?action=principal-list&session=value

The BREEZESESSION value is valid for only one login session. Your application must store a new cookie value each time the user logs in.

When you call the login action, you are sending a login ID and password across a network, unless you use external authentication. Use SSL or another appropriate security method to protect passwords in transit.

Request URL

http://server_name/api/xml
    ?action=login
    &login=string
    &password=string
    &account-id=integer
    &external-auth=use
    &domain=string

Parameters

Name	Type	Required	Description
`account-id`	Integer	N	The ID of your hosted account on Enterprise Hosted. If your organization uses Enterprise Server, do not use `account-id`.
`external-auth`	Allowed value	N	A value indicating whether you send an external network login ID to represent the user to Connect Enterprise. If so, use `external-auth=use`.
`login`	String	Y/N	The user's login name. Do not use if you use external or HTTP header authentication.
`password`	String	Y/N	The user's password. Do not use if you use external or HTTP header authentication.
`domain`	String	N	The domain name of your account on Enterprise Hosted. if your organization uses Enterprise Server, do not use `domain`.
`session`	String	N	The value of the `BREEZESESSION` cookie`.` Use this parameter if you do not use a client-side cookie management library.

Filters

Results cannot be filtered or sorted.

Response structure

<?xml version="1.0" encoding="utf-8" ?>
<results>
    <status code=allowedValue />
</results>

Response values

Element	Attribute	Type	Description
`results`		Container	All results the action returns.
`status`		Empty, with attributes	The status of the response.
	`code`	Allowed value	A code indicating the response status (see status).

Sample request

http://example.com/api/xml?action=login&login=joy@acme.com&password=happy
        &session=breeztg8mz53r93vebwur

Sample response

<?xml version="1.0" encoding="utf-8" ?>
<results>
    <status code="ok" />
</results>