Download OpenAPI specification:Download
Welcome to the Falcon API.
This technical documentation shows you how to interact with Falcon using our REST-API.
We appreciate your interest and hope to provide you with a detailed source of information. Please note that the documentation is still under construction and parts are still incomplete or missing. We are working under high pressure to complete a stable version.
The Falcon API is a RESTful API. Basically, all the functions you know from Falcon are available through the API.
You must specify a Content-Type header with each POST or PUT request so that Falcon can process the input data accordingly. For responses Falcon always uses the Content-Type application/json. Keep in mind that you always use UTF-8 as encoding.
All request payload is validated for each individual request. If your payload is incorrect, the response will contain validation errors with details.
The Content-Language header allows you to specify the language in which Falcon should respond. The header is evaluated according to the following definition. Currently Falcon supports the languages de and en.
The API endpoint URL is https://api.nordan.tech/.
If you want your personal sandbox environment, just create a test hub in the production environment and use it to test your application. You can use the registration on our website or simply sign in to Falcon with your username and password and create a new hub.
Only calls who passed authentication do count towards the call limit.
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.
Other restrictions for specific objects (e.g. the maximum length of strings, the range of integers) are documented in the individual API calls.
All date values in Falcon are stored in UTC timezone and will be serialized to a UTC ISO-8601 date string (RFC3339) (2016-08-14T22:34:02.000000Z).
For all date input values, the valid date formats are noted in each parameter description.
Basically, all endpoints except a few auth calls require a token of type JWT (JSON Web Token). You will receive this token in the response of an /auth call.
In order to authenticate a request, you can provide the token in several ways:
Authorization: Bearer <TOKEN> header (Recommended).query string in the URLinput in the request payloadBasic Auth password (Authorization: Basic BASE64(:<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.
The payload data of each token is formed from the following items:
| Field | Name | Description |
|---|---|---|
| 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 live | Time to live (in minutes) for the token. |
| sub | Subject | The user fingerprint for the token. |
| hsu | Hash subject | The hash of the subject model for the token. |
| pat | Token ID | The ID of the user token for the token. |
| ses | Session ID | The ID of the user 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 scopes of the token. |
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.
A used token is blacklisted with a grace period of 60 seconds and 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.
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.
You can exit the current hub by calling /auth/hub/invalidate or change the hub with /auth/hub. In both cases, the refreshed token will contain the new hub (or no hub if you just invalidated the hub).
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.
The validity of personal access tokens is always limited to one hub. It is therefore not possible to change a hub with this type of token.
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. The number of personal access tokens is unlimited - you can create as many tokens as you like for multiple hubs and determine the validity yourself.
A JSON web 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. Of course, you can renew the underlying personal access token at any time (even after expiration) in Falcon.
Multi-factor authentication is skipped if you authenticate with a personal access token.
Some routes cannot be used with personal access tokens. You can find an overview of these routes here:
In case of an authentication failure Falcon returns an failure code in the response. An overview of the authentication failure codes can be found here:
| Code | Failure | Description |
|---|---|---|
| 0 | Unknown | |
| 1 | Token not provided | The token is invalid. |
| 2 | Token expired | The session has expired. |
| 3 | Token blacklisted | The session is invalid or has expired. |
| 4 | Token invalid | The token is invalid. |
| 5 | Token scopes invalid | The token is invalid. |
| 6 | Token hub not provided | The token is invalid. |
| 7 | Token hub invalid | The current hub has been deactivated. |
| 8 | Token user invalid | The token is invalid. |
| 9 | Token user session invalid | The session is invalid or has expired. |
| 10 | Token user token invalid | The user token is invalid or has expired. |
| 11 | User credentials invalid | The credentials do not match our records. |
| 12 | User credentials password compromised | The user password has appeared in a data leak and has been reset for security reasons. |
| 13 | User login confirmation code invalid | The confirmation code is invalid or has expired. |
| 14 | User login confirmation status invalid | The security settings of the hub require the activation of multi-factor authentication. |
| 15 | User login confirmation channel invalid (SMS or authenticator channel required) | The security settings of the hub require the activation of multi-factor authentication through SMS confirmation. |
| 16 | User login confirmation channel invalid (authenticator channel required) | The security settings of the hub require the activation of multi-factor authentication with any authenticator app. |
| 17 | User disabled | The user has been deactivated. Please contact our support. |
| 18 | User hub unauthorized | The user does not have the required permissions for the hub. |
| 19 | User session terminated | The session has been terminated. |
| 20 | User session limit exceeded | The session limit has been exceeded. |
| 21 | User network invalid | The IP address of the user does not belong to an allowed network. |
| 22 | User invitation invalid | There is no valid invitation for this user. |
| 23 | Verification invalid | The verification link is invalid or has expired. |
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. The four most common client errors are:
Unauthorized
{- "success": false,
- "error": {
- "status": 401,
- "message": "Oops! Your token is invalid. Please sign in again.",
- "code": 4
}, - "timestamp": 1669630792358
}Forbidden
{- "success": false,
- "error": {
- "status": 403,
- "message": "You do not have the required permission to perform this action.",
- "code": 0
}, - "timestamp": 1653056069191
}Not Found
{- "success": false,
- "error": {
- "status": 404,
- "message": "Oops! The requested resource could not be found.",
- "code": 0
}, - "timestamp": 1655800020817
}Unprocessable Content
{- "success": false,
- "error": {
- "status": 422,
- "message": "The given data was invalid.",
- "errors": {
- "password": [
- "The password field is required when token is not present."
], - "token": [
- "The token field is required when password is not present."
]
}
}, - "timestamp": 1653639225756
}An overview of all possible client errors:
| Code | Message | Description | Possible causes |
|---|---|---|---|
| 401 | Unauthorized | Authentication failed. |
|
| 403 | Forbidden | Missing permission to perform the action. |
|
| 404 | Not Found | Requested resource could not be found. |
|
| 405 | Method Not Allowed | Invalid request method. | |
| 418 | I'm a teapot | The server refuses the attempt to brew coffee with a teapot. | |
| 422 | Unprocessable Content | Invalid request data. | |
| 429 | Too Many Requests | Too many requests to Falcon in the last minute. |
|
For errors on the server side Falcon returns a HTTP 5XX status code.
| Code | Message | Description |
|---|---|---|
| 500 | Internal Server Error | Oops! This shouldn't have happened. We will take care of this problem as soon as possible. |
| 502 | Bad Gateway | Oops! A service used by Falcon sends an invalid response. |
| 503 | Service Unavailable | Oops! Falcon is currently down for maintenance. Be right back! |
| 504 | Gateway Timeout | Oops! A service used by Falcon is unavailable. |
Falcon Precognition allows you to predict the result of a future HTTP request. One of the main use cases of Precognition is the ability to provide "live" validation for your application without having to duplicate the validation rules of the Falcon API.
When Falcon receives a precognitive request, it runs all of the route's middleware and resolves the route's controller dependencies, including validating form requests - but it does not run the route's actual controller method.
To use Falcon Precognition, you only need to add the Precognition: true header to an API request.
The Precognition: true header tells Falcon that a client is attempting a Precognition request. The optional Precognition-Validate-Only: <FIELD> header tells Falcon that a client only wants to run the validation rules for the <FIELD> input.
If the validation was successful, the response 204 No Content is returned with the header Precognition-Success: true. If, on the other hand, it was not successful, the normal error response 422 - Unprocessable Content is returned. In addition, the response always contains the header Precognition: true to indicate that it belongs to a Precognition request.
disposition query paramter to attachment, export and report download route.locale attribute to the new settings array of the user in the auth response.user_hub_permission to all user attributes in permission responses, e.g. for the user of a measurestatus attribute to all user that are part of the responses, e.g. for the responsible user of a user measure permissionsubject attribute to measure status report, measure package status report, project status report, and program status reportbudgeting attribute to budgeting item index and budgeting item show responsebudgeting attribute to budgeting category index and budgeting category show responseworkflow attribute to workflow phase index and workflow phase show responsefeatures attribute to authenticate without mfa, authenticate with code, authenticate with token, authenticate refresh, authenticate change hub, and create hub responseformat attribute to budgeting itemcalculation to aggregation_type_horizontal and aggregation_type_vertical for budgeting itemsttl attribute from the session to the auth responsestart_time_actual_overwritten (to all activity and workflow phase responses) and end_time_actual_overwritten (to all activity responses) attributestart_time_actual and end_time_actual for activity (create and update) and workflow phase (update) requestsmeasure, measure_id, measure_hash)calculation attributedescription, targets, assumptions, miscellaneous, comment, risks and decisions attributes