All our webservices use session based authentication through our Authenticate webservice. To improve performance and ease the stress on our servers, you should store the sessionId on your side so you don't authenticate unnecessarily. If you repeatedly authenticate with the same credentials, your requests will be throttled.
The SessionId is added to a cookie with the name “ASP.NET_SessionId” and sent to every webservice that you use.
# Get up and running with authentication
To get started using our webservices, please follow these steps:
- Initialize a SoapClient/WebService-object to Authenticate
- Check if there is an ASP.NET_SessionId saved (see step 4), if yes, go to step 5
- Log in using the Login method. The Login method uses a Credential object as parameter, which requires username, password and ApplicationID. The username is always an email address (community user).
- Save the ASP.NET_SessionId that is returned from the Login method (Save it on your side using Database/Cookies/Session/Etc)
- Check if ASP.NET_SessionId is still alive at 24SevenOffice by using AuthenticateService’s HasSession method. If it does not, go to step 3.
- Initialize a SoapClient/WebService-object to the Webservice that you want to use
- Set the cookie with the name “ASP.NET_SessionId” to the SessionId-value you confirmed in step 5, and pass this cookie along to the webservice that you’re going to use.
Visual Studio users: You need to add Web References your project by following this simple guide : Add Web Reference
To authenticate you use the Login-method with a Credential object. Mandatory fields are: ApplicationId, Username and Password. IdentityId does not need to be set, but can be used to control which Identity the login defaults to. Username is always an email address
<credential> <ApplicationId>guid</ApplicationId> <IdentityId>guid</IdentityId> <Password>string</Password> <Username>string</Username> </credential>
If the login was successful you will get a Login Response containing your SessionId:
<LoginResponse xmlns="http://24sevenOffice.com/webservices"> <LoginResult>xxxxxxxyyyyyyyyyzzzzzzzz</LoginResult> </LoginResponse>
# Sessions, identities and community users
There are some important concepts that you need to be familiar with. When you have done a successful request to Login (opens new window), you will get a SessionId in return. This SessionId is linked to a default Identity. In an integration you need to have some interaction with your user to make sure that the integration uses the correct Identity. You need to make a request to GetIdentities (opens new window) in order to get a list of available Identities for a given session. You then have to present this list to your user. The relevant information for the user is the Name of the Client
<Client> <Id>long</Id> <Name>string</Name> </Client>
Once the user has chosen a client and it is not the current or default client, you need to switch the Identity.
# Switching Identities
Your community user has a default identity when you log in. If there are several Identities associated with your community user, you invoke the GetIdentities method to get a complete list. Now you may switch to another Identity by using SetIdentity (pass the whole Identity object) or SetIdentityById (pass the Identity Guid). You may also set the Identity directly in your requests to Login by using the IdentityId property.
Please note: The IdentityId can change, so you should always implement checks to see which Identity is currently active. The IdentityId can change if an Identity is removed and then readded to a community user.
# Adding Identities
In order to add identities you need an invitation to the client. Your customer often has access to this, so an administrator can send an invitation to the community user that is used in the integration. Otherwise you can contact email@example.com for help with this.
Once you have been invited, you have to log in with the user and accept the invitation by clicking on the notification in the upper right corner.
|Method||Input Type||Return type||Description|
|Login (opens new window)||Credential||string||Authenticates the user and returns the session ID|
|HasSession (opens new window)||-||bool||Returns whether or not the current session is valid|
|GetIdentities (opens new window)||-||identity||Returns a list of community Identities|
|SetIdentity (opens new window)||identity||bool||Sets a current identity|
|SetIdentityById (opens new window)||identity||bool||Sets a current identity by its Guid|
|GetIdentity (opens new window)||-||identity||Returns the current identiy|
|AuthenticateByToken (opens new window)||Token||Passport||Authenticates with the given token and returns the passport.|