This is the documentation of the Falcon application.
WIP: This documentation is currently still in progress.
The Falcon API is a RESTful API. The requests and responses are formatted according to the JSON API specification.
The API endpoint URL is https://api.nordan.tech/.
Don't want to work with your live data? For a sandbox environment, you can simply create a test hub and use it to test your application. Simply sign in to Falcon with your username and password and create a new hub. Alternatively, you can use the registration on our (website).
Our API limits the submission of requests for your application. The limits are managed as the allowed number of operations per time window; an operation can be a read or an update. For authenticated endpoints, API calls are limited to
1000 requests per
60 seconds time window for a user. For unauthenticated endpoints, the limit is
100 requests per
60 seconds time window.
Each response contains the following headers:
X-RateLimit-Limit: Maximum number of operations allowed in the current time window.
X-RateLimit-Remaining: Number of operations remaining in the current window.
Once the limit is reached, a
429 Too Many Requests response code will be returned along with a
Retry-After header, which holds the amount of seconds until a new call can be made.
Only calls who passed authentication do count towards the call limit.
Other restrictions for specific objects (e.g. the maximum length of strings, the range of integers) are documented in the individual API calls.
The payload data of each token is formed from the following items:
|iss||Issuer||Issuer who created and signed the token.|
|jti||JWT ID||Unique identifier for the token.|
|nbf||Not before||Token is not valid before this unix timestamp.|
|iat||Issued at||Token is issued at this unix timestamp.|
|exp||Expiration time||Expiration unix timestamp for the token.|
|ttl||Time to life||Time to life (in minutes) for the token.|
|sub||Subject||The user fingerprint for the token.|
|hsu||Hash subject||The hash value of the subject for the token.|
|ses||Session ID||The ID of the session for the token.|
|hub||Hub ID||The ID of the hub for the token.|
|mfa||Multi factor authentification||Flag for multi factor authentification for the token.|
|scp||Scopes||The scope of the token.|
A token is only valid for the hub for which it was issued. Attempting to access an item from a different hub with a token that was not issued for that hub will always result in a
404 Not Found response.
Falcon basically provides two ways to authenticate. We recommend that you create a personal access token instead of using a password for the API.
Using the default method, you authenticate with the user's password.
All tokens have a validity of
30 minutes by default. This time can be extended to
30 days if you send the
remember: true parameter with the /auth call.
A token created by the password procedure will be automatically renewed with every request and extended for
30 minutes or
30 days. The refreshed token is returned along with an
Authorization: Bearer <TOKEN> header in the response.
A used token is blacklisted with a grace period of
60 secondsand cannot be used after that. Make sure to update the token after each request in your client and use the new token for the next request.
The password authentication may require multi-factor authentication if the user has enabled it or a new device is detected. To complete the authentication you must provide a valid
code with the /auth/code request.
You can create your own personal access tokens in Falcon and use them instead of a user's password.
A personal access token is like a password and should therefore be kept secret under all circumstances.
Personal access tokens can only be created for a specific hub. You can create as many tokens as you like and determine the validity yourself.
A JWT token created by authentication with personal access token has a fixed validity that you can determine yourself. These tokens are not renewed after each request and cannot be renewed manually.
The validity is always limited to one hub. A hub change is therefore not possible with this token. The number of personal access tokens is unlimited - you can have as many as you need for multiple hubs.
Multi-factor authentication is skipped if you authenticate with a personal access token.
For successful requests, Falcon returns the HTTP 2XX status codes. For a successful create process Falcon returns the response code 201, otherwise 200.
For client side errors, Falcon returns a HTTP 4XX status code if something passed in the request has an error.
|Status Code||Message||Description||Possible cuases|
|401||Unauthorized||Invalid Token||* Token expired.
* Hub expired.
|403||Forbidden||Missing permission to perform the action.||* Contact your hub admin for permissions for the element.
* Invalid signature.
|404||Not found||Resource could not be found.||* Route doesn't exists.
* Element doesn't exists.
* Element doesn't exists in the given hub from the token.
* Image not readable.
|405||Method Not Allowed||Invalid request method.||* Check the method for the request.|
|418||I'm a teapot||The server refuses the attempt to brew coffee with a teapot.||* Drink tea.|
|422||Unprocessable Content||Invalid request data.||* Check the "errors" array for detailed error message.|
|429||Too Many Requests||Too many requests to Falcon in the last minute.||* Too many requests.
* Too many authorization attempts.
* Too many password resend attempts.
* Too many sms send attempts.
For errors on the server side Falcon returns a HTTP 5XX status code.
|502||Bad gateway||A service used by Falcon send an invalid response.|
|503||Service unavailable||Falcon unavailable due to mainteance mode.|
|504||Gateway timeout||A service used by Falcon is unavailable.|