Authenticate User POST
Use the authenticate method to obtain credentials that identifiy the authorised user when making future API requests. Authorisation credentials are returned in the form of a bearer token or session cookie.
Request Parameters
| Parameter | Description |
| type Enumeration | Determines the type of authorisation credentials returned in the response: either a bearer token or session cookieRequired |
| username String | The username or email address associated with the user account to authenticateRequired |
| password String | The password for the user account to authenticateRequired |
Response Parameters
| Parameter | Description |
| realm String | The domain for which the authorisation credentials are valid |
| token String | The bearer token to use for future authorisationOptional |
| expires Date / Time | The date from which the bearer token is no longer valid for authorisationOptional |
Authorisation Type (Request)
| Value | Description |
| Session Cookie |
| Bearer Token |
Request Schema
<?xml version="1.0" encoding="utf-8"?>
<xsd:schema elementFormDefault="qualified" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="authenticate">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="type">
<xsd:annotation>
<xsd:documentation>Determines the type of authorisation credentials returned in the response: either a bearer token or session cookie</xsd:documentation>
</xsd:annotation>
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="session">
<xsd:annotation>
<xsd:documentation>Session Cookie</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
<xsd:enumeration value="token">
<xsd:annotation>
<xsd:documentation>Bearer Token</xsd:documentation>
</xsd:annotation>
</xsd:enumeration>
</xsd:restriction>
</xsd:simpleType>
</xsd:element>
<xsd:element name="username" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The username or email address associated with the user account to authenticate</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="password" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The password for the user account to authenticate</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Example Request
POST https://api.xure.co/v1/authentication/login.eb HTTP/1.1
Accept: text/xml
Content-Type: text/xml; charset=utf-8
<?xml version="1.0" encoding="utf-8"?>
<authenticate>
<type>xsd:string</type>
<username>xsd:string</username>
<password>xsd:string</password>
</authenticate>
Response Schema
<?xml version="1.0" encoding="utf-8"?>
<xsd:schema elementFormDefault="qualified" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="authorization">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="realm" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The domain for which the authorisation credentials are valid</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="token" minOccurs="0" type="xsd:string">
<xsd:annotation>
<xsd:documentation>The bearer token to use for future authorisation</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="expires" minOccurs="0" type="xsd:dateTime">
<xsd:annotation>
<xsd:documentation>The date from which the bearer token is no longer valid for authorisation</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
Example Response
HTTP/1.1 200 OK
Content-Type: text/xml
<?xml version="1.0" encoding="utf-8"?>
<authorization>
<realm>xsd:string</realm>
<token>xsd:string</token>
<expires>xsd:dateTime</expires>
</authorization>
Example Request
POST https://api.xure.co/v1/authentication/login.eb HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
{"type":String,
"username":String,
"password":String}
Example Response
HTTP/1.1 200 OK
Content-Type: application/json
{"realm":String,
"token":String,
"expires":String}
Status and Error Codes
| HTTP Status | Error Code and Description |
| 200 | User was successfully authenticated |
| 400 | DataError:password:RequiredRule Password must be provided |
| 400 | DataError:type:RequiredRule Authorization type must be specified |
| 400 | DataError:username:RequiredRule Username must be provided |
| 400 | OperationError:AuthenticationFailed User authentication failed due to incorrect username or password |
Authenticating your API access
There are three ways to autenticate your access to the Xure API and these are described in the table below.
The recommended method is to request a bearer token through the authenticate method. If you are unable to send custom headers with your API requests then, as alternatives, you can request a session cookie or use basic HTTP authentication against any API endpoint.
| Authentication Method |
How To Use |
| Bearer Token (preferred) |
Call the authenticate method with the type parameter set to "token", suppyling the username and password associated with a Xure user account.
If successful, the response contains a new bearer token in the token parameter. This should be submitted in the Authorization header with all further API requests.
The token is valid for use up until the date given in the expires parameter at which point a further authentication request is required to obtain a fresh token. Generally, bearer tokens are valid for a period of thirty days from issue.
|
| Session Cookie |
Call the authenticate method in the same way but with the type parameter set to "session".
If successful the token element will be returned empty, but the response headers will contain a session cookie that should be submitted with all further API requests.
When using a session cookie with the API, if no further requests are made for a period of 30 minutes the cookie will become invalid and a further authentication request will need to be made.
|
| Basic HTTP Authentication |
If you are making requests through software that does not support custom headers or cookies then you can use basic HTTP authentication instead. This requires submission of your username and password with every request. Follow the instructions for your software on how to configure HTTP authentication. |
Setting the Authorization header
Once you have obtained a bearer token, provide the token in the Authorization header of future requests to authorise further access to the API:
GET https://api.xure.co/v1/live/sites.eb HTTP/1.1
Accept: text/xml
Authorization: Bearer [token]
The token value is prefixed by the word "Bearer" followed by a space.