Authentication

Learn how to securely authenticate with our API and understand how access is tied to the party type of the account issuing the tokens.

Requests use the HTTP Authorization header to authorize operations. The facilioo API accepts bearer tokens (JWT) in this header. These bearer tokens can be obtained using the /api/auth/login or /api/auth/refresh method.

📘
Level of Access
Access levels in the facilioo API depend on multiple factors. Beyond dynamic runtime checks, a core aspect is the party type your account belongs to — such as a property management company, contractor, or user. This information is embedded in the accessToken and determines which resources and operations are available.
To learn more about how accounts and party types relate, see the Parties and Accounts documentation.

Login

Attribute	Type	Description
`email`	`string`	Email of the user
`password`	`string`	The password of the user
`skipMultiFactorAuthentication`	`boolean`	If `true`, the user will not be asked for multifactor authentication

Access Token (JWT)

Both access tokens and refresh tokens use JWT open standard.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYmYiOjE2NTE3NjAyNDIsImV4cCI6MTY1MTc2Mzg0MiwiaXNzIjoiZGV2LWFwaS5mYWNpbGlvby5kZSIsImF1ZCI6ImRldi1hcHAuZmFjaWxpb28uZGUiLCJzdWIiOnsiYWNjb3VudElkIjoyLCJjb21wYW55SWQiOjJ9fQ.KJPsiOzcu8SHXU_GhGz5qS6cg-moXAC83WOLI8J9vFLgk5k0MdkxR8S88Ri0BJuCmifFtHpbR7bH4tKxeF8-pW_wU08uQ_MJxJqcK9MOjyVITsLzok7RJxqevv0SjPZkgqqxGwgGbcgsYJaG2u44RYnnyf5xPce9MKQcfHa23C-NyQIBmseO7RdFNAFZM8Lc-nEf0tjJc3ciBdr7t_s8dUS2vCb4ALWj8Dhrs9UyO3bA1yMQt4xACfQzGbDMV_4R8nbgOL9KkywcmJD-JdcIiYIGk2GEhbhuL05CtJthZT4XWVE0wdA00YmDBdvuekzykDKalXU2C1ED3winvL6VGg

Note: The example token has expired and can't be used for authorization.

Type Decoded (Example) Description

Header { "alg": "RS256", "typ": "JWT" } That does only specify the type of token an algorithm used.

Payload

Type	Decoded (Example)	Description
Header	`{ "alg": "RS256", "typ": "JWT" }`	That does only specify the type of token an algorithm used.
Payload	`{ "sub": "2", "partyId": "2", "partyName": "Demo Hausverwaltung", "accountRole": "2", "email": "[email protected]", "scope": "platform", "permissions": "/v3//z/w/c/1IwAa/We23/kGAA==", "telemetry": "{\"UnitCount\":10,\"ProcessCount\":25}", "iat": 1651760242, "exp": 1651763842, "iss": "api.facilioo.de", "aud": "app.facilioo.de" }`	The `sub` attribute is the account ID the token was issued for. The `partyId` attribute is the ID of the party (e.g. property management company) the account belongs to, and `partyName` its display name. The `accountRole` attribute is the numeric party type of the account (e.g. property management company, contractor, user) and is what determines the level of access described in the note above. The `email` attribute is the account's email address. The `scope` attribute specifies the purpose of the token, e.g. `platform` for a normal, fully authenticated session as opposed to narrower-purpose tokens (such as ones issued during a password-change or multi-factor-authentication flow). The `permissions` attribute is a compact, encoded representation of the account's permission set, computed at token creation time from the permissions of the account group the account belongs to. These `AccountPermissions` are also exposed via the API (as the caller's own effective permission set); the mapping between an account group and its permissions is not yet exposed via the API. The `telemetry` attribute, present only for property management company accounts, reports current usage figures (such as managed unit and process counts) for that account. The attribute `iat` specifies the time the token was issued. The attribute `exp` does specify the time the token will expire. Expired tokens can't be used for authentication. The `iss` attribute specifies the issuer of the token, which will be the facilioo API. The `aud` attribute does specify the intended audience of the token and therefore the system (domain) which can use the token. For more information about claims, please refer to RFC 7519 .
Signature	<omitted>	<omitted>

{           "sub": "2",           "partyId": "2",           "partyName": "Demo Hausverwaltung",           "accountRole": "2",           "email": "[email protected]",           "scope": "platform",           "permissions": "/v3//z/w/c/1IwAa/We23/kGAA==",           "telemetry": "{\"UnitCount\":10,\"ProcessCount\":25}",           "iat": 1651760242,           "exp": 1651763842,           "iss": "api.facilioo.de",           "aud": "app.facilioo.de"         }

The sub attribute is the account ID the token was issued for.

The partyId attribute is the ID of the party (e.g. property management company) the account belongs to, and partyName its display name.

The accountRole attribute is the numeric party type of the account (e.g. property management company, contractor, user) and is what determines the level of access described in the note above.

The email attribute is the account's email address.

The scope attribute specifies the purpose of the token, e.g. platform for a normal, fully authenticated session as opposed to narrower-purpose tokens (such as ones issued during a password-change or multi-factor-authentication flow).

The permissions attribute is a compact, encoded representation of the account's permission set, computed at token creation time from the permissions of the account group the account belongs to. These AccountPermissions are also exposed via the API (as the caller's own effective permission set); the mapping between an account group and its permissions is not yet exposed via the API.

The telemetry attribute, present only for property management company accounts, reports current usage figures (such as managed unit and process counts) for that account.

The attribute iat specifies the time the token was issued.

The attribute exp does specify the time the token will expire. Expired tokens can't be used for authentication.

The iss attribute specifies the issuer of the token, which will be the facilioo API.

The aud attribute does specify the intended audience of the token and therefore the system (domain) which can use the token.

For more information about claims, please refer to RFC 7519 .

Signature <omitted> <omitted>

Refresh

When an access token reaches its expiration, any subsequent API call will result in a status code 401 Unauthorized error. To resolve this, the client should initiate a call to the refresh token endpoint. It is essential for the client to persistently store the refresh token.

By utilizing the refresh token in this scenario, the client can obtain both a new access token and a new refresh token. The newly received refresh token should be saved and used for all future refresh requests.

Request

Attribute	Type	Description
`refreshToken`	`string`	One-time usable refresh token from the last login or refresh request.

Response

Attribute	Type	Description
`accessToken`	`string`	The access token, which can be used to make new requests.
`refreshToken`	`object`	The refresh token to generate a new set.

Debugging

Use jwt.io to have a look at the tokens content.

Customer App Password Reset Flow

The password reset flow allows users to recover their account in case they forget their password. It consists of three main steps: sending a recovery email, changing the password using a recovery code, and unblocking the recovery code if necessary.

1. Initiate Password Recovery

Endpoint: POST /api/auth/recover-password
Description: Sends a password recovery message to the user’s email. This operation is rate-limited using the DefaultRateLimitAuth policy.

Behavior:

The user provides their registered email address.
The system sends an email with a recovery code or a link containing the recovery code.
Rate limiting prevents abuse of this endpoint.

Note: This endpoint is currently marked as obsolete and will be removed once an external identity provider is implemented.

Example Request DTO:

{
  "email": "[email protected]"
}

Response DTO: PasswordRecoveryResponseDto

2. Change Password Using Recovery Code

Endpoint: PUT /api/auth/change-password-with-recovery-code
Description: Changes the user’s password using a recovery code received via email.

Behavior:

The user enters the recovery code received in their email, along with the new password.
The system validates the recovery code and updates the user’s password.
If the user enters the wrong recovery code 5 times, the account will be temporarily blocked for 24 hours.

Example Request DTO:

{
  "email": "[email protected]",
  "password": "newSecurePassword",
  "recoveryCode": "123456"
}

Response DTO: PasswordChangeRecoveryCodeResponseDto

Note: This endpoint is also marked as obsolete and will be removed once an identity provider is implemented.

3. Unblock Recovery Code

Endpoint: POST /api/account/unblock-recovery-code
Description: Unblocks a user’s recovery code if the account has been temporarily blocked due to multiple failed attempts.

Behavior:

Requires authentication with either an Admin or PropertyManagementCompany role.
The request must include the account’s email address.
The owner of the account (typically a PropertyManager) can unblock the recovery code.

Example Request DTO:

{
  "email": "[email protected]"
}

Response DTO: UnblockRecoveryCodeResponseDto

Note: This endpoint is marked as obsolete and will be removed once an identity provider is implemented.