API » Version 1 » Authentication

Validates user credentials and generates an authentication token to authorise future API requests

Authenticate POST

Use the authenticate method to obtain the identification to use for future requests to access secure data.

With the authorization type set to "token" this method will return a token that identifies an authorised user when making future requests. Tokens are valid for a period of thirty days from issue. The token should be submitted in the Authorization header of future requests, preceded by the word "Bearer".

With the authorization type set to "session" this method will set a temporary cookie that identifies the authorised used for future requests.

Parameters

Request Parameters
ParameterNameTypeDescription
typeAuthorisation TypeEnumerationDetermines the type of authorisation credentials returned in the response: either a bearer token or session cookie
usernameUsernameStringThe username or email address associated with the user account to authenticate
passwordPasswordStringThe password for the user account to authenticate
Response Parameters
ParameterNameTypeDescription
realmRealmStringThe domain for which the authorisation credentials are valid
tokenTokenString (Optional)The bearer token to use for future authorisation
expiresExpiresDate / Time (Optional)The date from which the bearer token is no longer valid for authorisation

Enumerations

Authorisation Type (Request)
ValueDescription
sessionSession Cookie
tokenBearer Token

XML

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.casi.services/v1/authenticate.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>

JSON

Example Request
POST https://api.casi.services/v1/authenticate.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 Codes

Status and Error Codes
HTTP StatusError CodeDescription
200  
400DataError:password:RequiredRule

Password must be provided

400DataError:type:RequiredRule

Authorization type must be specified

400DataError:username:RequiredRule

Username must be provided

400OperationError:AuthenticationFailed 

Test

Determines the type of authorisation credentials returned in the response: either a bearer token or session cookie
The username or email address associated with the user account to authenticate
The password for the user account to authenticate

Get User Details GET

Obtain details of the user account associated with the supplied authentication token

Parameters

Response Parameters
ParameterNameTypeDescription
IsAuthenticatedIs AuthenticatedBooleanFlag indicates if an authenticated user is associated with the request
AuthenticatedUsernameAuthenticated UsernameString (Optional)The username assigned to the current authenticated user
AuthenticatedNameAuthenticated NameString (Optional)The full name of the current authenticated user

XML

Example Request
GET https://api.casi.services/v1/authenticate.eb HTTP/1.1
Accept: text/xml
Response Schema
<?xml version="1.0" encoding="utf-8"?>
<xsd:schema elementFormDefault="qualified" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <xsd:element name="UserDetails">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="IsAuthenticated" type="xsd:boolean">
          <xsd:annotation>
            <xsd:documentation>Flag indicates if an authenticated user is associated with the request</xsd:documentation>
          </xsd:annotation>
        </xsd:element>
        <xsd:element name="AuthenticatedUsername" minOccurs="0" type="xsd:string">
          <xsd:annotation>
            <xsd:documentation>The username assigned to the current authenticated user</xsd:documentation>
          </xsd:annotation>
        </xsd:element>
        <xsd:element name="AuthenticatedName" minOccurs="0" type="xsd:string">
          <xsd:annotation>
            <xsd:documentation>The full name of the current authenticated user</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"?>
<UserDetails>
  <IsAuthenticated>xsd:boolean</IsAuthenticated>
  <AuthenticatedUsername>xsd:string</AuthenticatedUsername>
  <AuthenticatedName>xsd:string</AuthenticatedName>
</UserDetails>

JSON

Example Request
GET https://api.casi.services/v1/authenticate.eb HTTP/1.1
Accept: application/json
Example Response
HTTP/1.1 200 OK
Content-Type: application/json

{"IsAuthenticated":Boolean,
  "AuthenticatedUsername":String,
  "AuthenticatedName":String}

Status Codes

Status and Error Codes
HTTP StatusError CodeDescription
200  

Test