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
accessTokenand 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
-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEAuM8mReeVOc3gMUu5C2BCOUY0CWt/L9ptlGQ5Bfjo7vI6klZILp5h
E+y2ctW3TiSml3q5C7PVkjbm2sJS6Fw6Ift/oICiWlhtAJSSgst21vCQ+W41iU2j
UicCQCfOe92UJBoOBIDVSsLFVdA06f+gvGPIulo0T3vrZDBYmyni7foCA0VBM3by
NcHs4bWQi8xxvqURkdqVJu/rMVNdsxfyErnb0jH5o5iHBp0VPYFem1FiwWdnVMT+
aRb0T6bbvyP0GKpfBcfMOwrbfA9Q7JPft00Yhyea3Sgg7cCJFii/aolc4egDvpsM
t5nq00NQSj6+0aVyynH8TSXMUoSZK9MRYwIDAQAB
-----END RSA PUBLIC KEY----
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 |
| Payload | { "nbf": 1651760242, "exp": 1651763842, "iss": "dev-api.facilioo.de", "aud": "dev-app.facilioo.de", "sub": { "accountId": 2, "companyId": 2 } } | The attribute nbf does specify the time that he token can be used the earliest. Therefore, the token can't be used before. In this example, that's on 2022-05-05T16:17:22+0200.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.The sub attribute does contain the information about the user, such as the accountId and the companyId.For more information about claims, please refer to RFC 7519 . |
| Signature | <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 |
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.