Library
Authentication
Each API provided is protected by a set of access rules. The API provided is the same as the internal Fieldpine used APIs but is restricted and controlled using security rules rather than creating a seperate API for more public use. The following outlines the various ways security might be applied to an API, keep in mind that each retailer can apply different rules.
Available Techniques
- X-Api-Key HTTP header.
- Basic-Auth over HTTPS. An X-Api-Key is typically still required as well.
- Negotiate (or NTLM). For internal networks only
No Security APIs
Some APIs have no security where the data is not considered private. For example APIs that provide validation services, such as checking an email for valid syntax, may not be protected. With this level of security you do not have to provide an X-Api-Header, but can if you wish.
Internal Network
In situations where the API caller inside your network or you are not concerned by X-Api-Keys being stolen, then simply place the X-Api-Key in the request header.
Internal networks are also able to use Negotiate and NTLM authentication schemes.
Single Use Tokens
In some cases a customer or browser may have a Url pointing to secure information. This url can include a "single use token" which is an opaque value that you can insert into the X-Api-Key to provide restricted access to a single resource. These are slightly different to general API calling but are mentioned so that all methods are clear. Single use tokens provide very granular access to resources that your webserver might not have general access too.
For example, a QR code might include a SUT (Single Use Token) to permit access to a single sales details; or a purchase order sent to a supplier
High Security APIs used from internet web server.
| User Browser or Mobile App | ||
| ⇳ | ||
| Retailers public WebServer |
⇳ | Protected API server |
Some APIs process sensitive information, or you need to protect the Api-Key. A web developer will often call the API from the web server host providing their secret Api-Key. With this approach the details of the backend API are invisible to the browser.
Works best on: With Firewall and Using Fieldpine configurations
Advantages
- Secure. API keys are not divulged to browsers and apps
- Easier to handle multiple API server hosts
Disadvantages
- Website developer needs to code interfaces and calls
- Website may need to pass some details of original browser, such as IP address or User-Agent
- Additional calling latency
Lower Security APIs used from directly from browser
| User Browser or Mobile App | (Lower Security API) | |
| ⇳ | ⇳ | |
| Retailers public WebServer | Protected API server |
If the API involved is of lower security or can be protected via source IP address locking, such as when an API is called from trusted suppliers, then the end user browser can directly call the API. This method can also be used if the retailers webserver has a login type function and can issue individual Api-Keys based on your login
Works best on: With Firewall and Using Fieldpine configurations
Advantages
- Development is client-only, no server side coding
- Api Server has direct access to original browser so can security validate directly
Disadvantages
- Api-Key is visible to end browser
- Some complexity if needing to handle multiple Api Servers
- Api needs to permit CORS
- Can expose Origin server IP address unless obscured
Medium Security APIs used from directly from browser
This method is not currently available but will be shortly
| User Browser or Mobile App | (Medium Security API) | |
| ⇳ | ⤡ | |
| Retailers public WebServer | Protected API server |
Medium security APIs are used to access sensitive data but without exposing your API key to the browser. The flow is broadly
- User browses to retailer website
- HTML includes an IFRAME to Api-Server. This is an invisible iframe, to process Javascript only
- HTML communicates to IFRAME with postMessage and can retrieve sensitive data
Works best on: With Firewall and Using Fieldpine configurations
Advantages
- Api Server has direct access to original browser so can security validate directly
- Can work for static hosted websites
- Api Server does not need to support CORS
Disadvantages
- Requires postMessage support in client browser
- Ideally servers should pass a token from server to Api-Server, and have the webpage postMessage this same token to the IFRAME. This requires server side coding but is more secure.
- Requires loading an IFRAME/script from fieldpine.com and client side scripting
- Can expose Origin server IP address unless obscured
Notes
APIs need to be specifically enabled for CORS support, they are not enabled by default for APIs that return data, but are generally enabled for validation type APIs. Please keep in mind that CORS is not a security mechanism, a skilled attacker can bypass CORs in some cases.
The API server can restrict by transport method, in general you should use HTTPS where possible
Requests to the server are rate limited and velocity controlled. The rate limits are high so you do not need to be concerned for normal operation. Velocity limits control the rate at which APIs can be called and are a common technique for financial applications. While the rate limit for an API might be 10,000 calls/hour the velocity limit might start slowing individual original IP addresses after 3 or 4 requests. In general the server will slow down response time as limits are approached, but may also return errors or simply close the network connection.
Different retailers may have different API servers. Premium rate customers may be using different hosts, while other retailers may be using the public servers. In general this has no bearing to you, but keep in mind that host servers can change.