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 user name 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 JWT in the response of an /auth call.
In order to authenticate a request, you can provide the JWT in several ways:
Authorization: Bearer <TOKEN> header (Recommended).query string in the URLinput in the request payloadBasic Auth password (Authorization: Basic BASE64(:<TOKEN>))A JWT is only valid for the hub for which it was issued. Attempting to access an item from a different hub with a JWT that was not issued for that hub will always result in a 404 Not Found response.
The payload data of each JWT is formed from the following items:
| Field | Name | Description |
|---|---|---|
| iss | Issuer | Issuer who created and signed the JWT. |
| sub | Subject | The user fingerprint for the JWT. |
| imp | Impersonated user | The impersonated user fingerprint for the JWT. |
| aud | Audience | Audience for whom the JWT was created. |
| nbf | Not before | JWT is not valid before this unix timestamp. |
| iat | Issued at | JWT is issued at this unix timestamp. |
| exp | Expiration time | Expiration unix timestamp for the JWT. |
| ttl | Time to live | Time to live (in minutes) for the JWT. |
| jti | JWT ID | Unique identifier for the JWT. |
| hsu | Hash subject | The hash of the subject model for the JWT. |
| pat | Personal access token ID | The ID of the personal access token for the JWT. |
| ses | Session ID | The ID of the user session for the JWT. |
| hub | Hub ID | The ID of the hub for the JWT. |
| mfa | Multi factor authentication | Flag for multi factor authentication for the JWT. |
| scp | Scopes | The scopes of the JWT. |
Falcon basically provides two ways to authenticate:
remember parameterWe 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 JWT is blacklisted with a grace period of 60 seconds and cannot be used after that. Make sure to update the JWT after each request in your client and use the new JWT for the next request.
All JWTs 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 JWT created by the password procedure will be automatically renewed with every request and extended for 30 minutes or 30 days. The refreshed JWT 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 JWT 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 JWT created by authentication with personal access token has a fixed validity that you can determine yourself. These JWTs 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 JWT is invalid. |
| 2 | Token expired | The session has expired. |
| 3 | Token blacklisted | The session is invalid or has expired. |
| 4 | Token invalid | The JWT is invalid. |
| 5 | Token scopes invalid | The JWT is invalid. |
| 6 | Token hub not provided | The JWT is invalid. |
| 7 | Token hub invalid | The current hub has been deactivated. |
| 8 | Token user invalid | The JWT is invalid. |
| 9 | Token user session invalid | The session is invalid or has expired. |
| 10 | Token user token invalid | The personal access token is invalid or has expired. |
| 11 | User credentials invalid | The credentials do not match our records. |
| 12 | User credentials password outdated | The user password has exceeded the maximum age for passwords. |
| 13 | User credentials password compromised | The user password has appeared in a data leak and has been reset for security reasons. |
| 14 | User credentials password insecure | The user password no longer complies with the password policies. |
| 15 | User login confirmation code invalid | The confirmation code is invalid or has expired. |
| 16 | User login confirmation status invalid | The security settings of the hub require the activation of multi-factor authentication. |
| 17 | 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. |
| 18 | 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. |
| 19 | User disabled | The user has been deactivated. Please contact our support. |
| 20 | User hub unauthorized | The user does not have the required permissions for the hub. |
| 21 | User session terminated | The session has been terminated. |
| 22 | User session limit exceeded | The session limit has been exceeded. |
| 23 | User network invalid | The IP address of the user does not belong to an allowed network. |
| 24 | User identity forbidden | The user does not have a valid email address. |
| 25 | User identity invalid | There is no valid identity for this user. |
| 26 | User identity provider disabled | The identity provider has been deactivated. |
| 27 | User identity provider required | The hub must be authorized with an identity provider. |
| 28 | User invitation invalid | There is no valid invitation for this user. |
| 29 | 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.
login_method parameter for authenticate with password and authenticate with token.access parameter was replaced by the umask parameter for create user route.position parameter to placement in the activity position request.position parameter to placement in the budgeting category position request.position parameter to placement in the budgeting item position request.position parameter to placement in the workflow phase position request.auth/password/reset route.password_update attribute from the auth responses.terms_reconfirmation attribute to terms_confirmation attribute in the auth responses.password_modified_time, password_age and password_age_relative_time attributes for foreign users.trial attribute with type attribute for a hub.accounting, accounting_ledger and accounting_legal_entity.id) to string (budgeting period name).id) to string (budgeting period name).domain attribute to the user responses, e.g. the user index response.imp claim to JWT payload.profile and process.elapsed_plan attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.elapsed_actual attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.start_time_plan_past attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.start_time_actual_past attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.end_time_plan_past attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.end_time_actual_past attribute to the measure schedule object in the measure show and index response, in the package show and index response, in the project show and index response, in the program show and index response.aud claim to JWT payload.signature attribute from all attachment responses.password_type attribute to the user in the auth response.paused attribute to all base elements in nested trees for measure attachments index route, for measure budgeting effect index and show, for measure budgeting total index and show, for measure status report index and show responses.paused attribute to all base elements in nested trees for measure package attachments index route, for measure package budgeting effect index and show, for measure package budgeting total index and show, for measure package status report index and show responses.paused attribute to all base elements in nested trees for project attachments index route, for project budgeting effect index and show, for project budgeting total index and show, for project status report index and show responses.paused attribute to all base elements in nested trees for program attachments index route, for program budgeting effect index and show, for program budgeting total index and show, for program status report index and show responses.overview for all reports and report subscriptions.id and hash attributes with measure object in the measure workflow phase response for multiple measures.id and hash attributes with program object in the budgeting period response without filter.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) attributemeasure, measure_id, measure_hash)calculation attributedescription, targets, assumptions, miscellaneous, comment, risks and decisions attributes