Authenticating with the RESTful API

Field Squared uses a RESTful API to send and receive data. This API conforms strongly to the Data Transfer Objects (DTO) pattern designed by Martin Fowler as outlined in Enterprise Integration Patterns.

All requests to the Field Squared API must authenticate with the Field Squared Authentication API. Authenticating with the Field Squared API is done using a combination of username, password and workspace ID which are your authentication credentials.

A Workspace ID is the unique identifier we assign to each customer.

The username and password are used by the Field Squared Authentication API to generate an Authentication Token (or "AuthToken").

The AuthToken must be attached to the HTTP Header of all subsequent requests made to the Field Squared API.

Field Squared API Request Basics

When making requests to the Field Squared API:

• All requests must use a HTTP header with X-Auth-Token as detailed below
• The API is stateless
• The API is RESTful in almost all cases
• The API supports both XML and JSON payloads
• HTTP methods (or "verbs") are significant – we support GET, PUT, POST and DELETE
• All traffic must be sent using HTTPS with SSL and TLS 1.2 or greater
• Unencrypted traffic will be rejected by the Field Squared servers at the firewall
• Traffic without a valid HTTP header will be rejected by the Field Squared Firewall

See our API usage notes for more details on our API specification and requirements.

Step 1 – Obtain an Auth Token

To obtain an authentication token (AuthToken), Field Squared will provide customers with

• a username
• a strong password
• a workspaceid – this is your customer id

Your API or enterprise service bus (ESB) then needs to make a HTTP POST request to the following URL:

https://api.fieldsquared.com/Authentication

The payload for this message must be in XML or JSON format per the following samples.

XML Authentication Message

XML Example

<Authentication xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Field2Office.API.Model.Authentication">
 <Email>String</Email>
 <Password>String</Password>
</Authentication>

JSON Authentication Message

{
   "Email" : "string",
   "Password" : "string"
}

The server will then send a HTTP response of 200 OK if you were successfully authenticated.

Sample XML Authentication Response

HTTP/1.1 200 OK 
Content-Type: application/xml
Content-Length: length

<AuthenticationResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/Field2Office.API.Model.Authentication">
   <AuthToken>String</AuthToken>
   <UserId>String</UserId>
   <Workspace>String</Workspace>
</AuthenticationResponse>

Sample JSON Authentication Response

HTTP/1.1 200 OK 
Content-Type: application/json
Content-Length: length

{
   "AuthToken": "String",
   "UserId": "String",
   "Workspace": "String"
}

The properties returned above will be used in all subsequent API calls.

Notes:

• The Authentication API is the only call in Field Squared's API that doesn't require the HTTP headers detailed in step 2 below. Plain HTTP headers are all that's required. You must specify JSON or XML however when making the request.
• Authentication should be performed only once per session. Subsequent calls to the Authentication API with the correct username and password will issue a new AuthToken for that account and invalidate any auth tokens previously issued immediately.
• We recommend not hard coding the Auth Token into your apps and instead always have a way to go fetch the Auth Token. Hard coding will work, but is subject to the points above.

Step 2 – Use the Auth-Token in all API requests

All future requests to the FS API must then be made using the following HTTP header fields in order to use the secure FS API: