The username/password authentication described below is being deprecated in favor of Api Keys. Api Keys will be released in Q1 2022.
Overview
The Flex5 REST API is in an early access stage and under heavy development & evolution. This is our "private" API that is being built to service our Flex5 Phone, Tablet, & Desktop applications.
It is very likely we will build a "public" API layer in the future with something like GraphQL. The reason is that this REST API is low-level, with a flat JSON structure. This means you will have to make a lot of individual API calls to gather all the data you need.
We envision a more public-friendly API in the future that allows external developers to better fetch & aggregate data in a single request.
API Terms & Conditions
Since this API is under heavy development & evolution (and could get replaced with a "public" API someday), we require that you sign off on an API Terms & Conditions document; you can find it here.
Download that document, fill it in, sign it, then go here to complete a request form. Once the request is received, we will review it, and if approved, we will provide you with a special "source" property which is needed to get authentication tokens.
Accessing Your Own API Documentation
Our API Documentation tool is Swagger UI. You can browse your own Swagger UI by using the template URL below.
Substitute in your own subdomain for "yourflexsite": https://yourflexsite.flexrentalsolutions.com/f5/swagger-ui.html
You can download the entire Swagger API definition by right-clicking the link below API Documentation (near the top of the screen) and using your browser's "Save As" feature. The link should look like https://yourflexsite.flexrentalsolutions.com/f5/api/api-docs.
An Authentication Example With The Flex5 Dev API
You can browse the cutting edge API's from Flex Dev here: https://flex5dev.flexrentalsolutions.com/f5/swagger-ui.html
First, let's get an Authentication Token by going to the above URL, then click Authentication and Try It Out. Replace the Example Value information (username/password/source) with that which you receive in response to sending the signed terms & conditions document.
The JSON should look something like the below. Notice the special "source" property, which is a special "key" that prevents unauthorized access to the API.
{
"username": "api-test",
"password": "password",
"source": "<will be provided>"
}
Next, click the Execute button. This will return a JSON response that looks something like below. Notice the "token" property. That is your authentication token. Copy that token and save it in a safe place.
{
"token": "eyJhbGciOiJIUzUxMiIsInppcCI6IkdaSVAifQ.H4sIAAAAAAAAAOVWTY_TMBD9LzkXq7vqUtobEhcOiL3ABXFw7WkyrGMHj5NuF_HfmaQfcbdOGsSRQxXVHr95fm9mkl8Z1ZtsnckK3wSgkM0y5UEG0Nn67mFxt1yuFvPVYjmfZQGstOEjb2RbA88PGhqOrsCXSITOUrb-1v0VlXc_QAUSDcLuGCO2yMcVSkPCg5JGXRwWaBuwwfl9fOi4p5wHURP497pEewJU_CullTkMIUUpYybtQQ0Gwumg2OCLq4h5o0KbJxj0mPBcOR_AX-63a9J0D8a9oHkWQztl63IDXrgGvEcNCWlSF1IlsQSW9Q9fmdnr3D23UqLtXFIp6LFbDTE4KYMlr1EsoIzueA3nvAJBRavKsD2jHoDGEOcjsIQBGxiqD1VIm8OjJNo5rxP3TyLEATLPPeQyMGQK_-DAp06etP1G7l194X7CooS_LTztKZb0JIfyTJm7JS3FjWoZ48or5Kw0-BJfuMMfELh0ujZwiRnLFzt2LnpmssX8ajmKvZJIudpeNVi_nXtXVzcan5QcdGDj3Y5AFKg1DAYdikn8rHnisdTn0k8MKx9qlrPNyMZ47K06Oti7RSC9KkRwT7yU7rOh4Lhi-4ES9884M2nMgDXdw6AKPJXJGZ5M0-7KiGK4zKXWwiYocyWD1dLf8C-RiRtrvKfETnooHL8m2nRlFShZwxs08Ij2c9VW_dms65gP0GA_Rtu24LHytDVux0KVPMEF8Lg19BfNFSeRdSiYPrc2v2q_UN9Q_1wI0w2eaMuQKFN0nSzctHfHyKD_f3T7Psv4I-Twefbu_v7tfPX7D4ARUHjGCQAA.tgbY7Wsje-qyiP99xfXSGtJ3-3JBOhpJUGnSRbwcsshrOIwbrEy7LcoQ7NSI4INxhyWo6hV6V3KzXyYE6uniqA",
"user": {
"id": "3820fee0-5fa1-11e8-bc43-12aef1b28bdc",
"name": "Api Test",
"userName": "api-test",
"emailAddress": "api-test@flexrentalsolutions.com"
}
}
In Swagger, there is an Authorize button in the top right. Copy the token property, click the Authorize button, paste it in the Value field and click the next Authorize button. Now you are logged in and can begin to play around with the other endpoints inside Swagger UI.
Note: you will need to repeat this process for your own URL. Also, note that your Flex site will only show the currently available public APIs which will differ from the flex5dev offerings.
Writing Your Own Code
When you write your code against the API, the process will be similar. You'll have to post to the authentication endpoint to get a token and then send it down in the X-Auth-Token header for ALL requests.
If your token has aged approximately 1 hour, the server will kick out a refresh token in the X-Auth-Token-Refreshed header. Our app just sniffs for the refresh token on each request, and if it finds one, it replaces the current one and starts sending the new one.
A Flex Api token lasts approximately 12 hours and then expires. You should cache the token somewhere safe and sniff for a new token on every request. Replace the existing token when you see a new one.
If you had a long period between requests and your token has expired, you'll get a 401 UNAUTHORIZED. You can detect that, and send a new /auth request to get a new token.
Understanding Flex5 API
You will not be able to fully comprehend the Flex5 API only using the Swagger UI. Since the Flex5 UI uses the Flex5 API, you can use your browser's network tool to observe which APIs are being used, query parameters passed to the API, and JSON data being sent and received to and from the API.
Using Chrome as the browser, visit your Flex site and login. Now open Chrome DevTools by going to Chrome's Menu → View → Developer → Developer Tools. Open the Network tab at the top. You'll now be able to see everything accessing the Flex5 API. Return to the regular Chrome browser and continue to use the Flex5 UI to get/create what you are attempting to write code against the Flex5 API for. As you use the software, you'll begin to build up a log of network activity that will now help you understand which APIs to call and what data to pass in.