Justimmo OAuth

Justimmo auth server can act as an OAuth provider for third party software. https://tools.ietf.org/html/rfc6749

Prequesites

Please contact support@justimmo.at for further information.

Supported grant types

Grant type	Resource access	Auth code	Access token	Refresh token
Authorization code	global, personal, client	1 minute	1 day	1 month
Refresh token	global, personal, client	-	1 day	1 month
Client credentials	global, client	-	1 day	-

Authorization code grant

The authorization code grant allows you to access personal resources of a user and any other resources the user has access to.

Request the auth code

Redirect your user to

info

https://auth.justimmo.at/authorize?response_type=code&client_id={your_client_id}&redirect_uri={redirection_uri_after_successfull_authorization}

On this page the user will be request to authenticate in Justimmo and to authorize your client to access certain resources and scopes. After the process Justimmo will redirect the user to the provided redirect_uri and add additional parameters depending on the success of the authorization process.

If the user declined the authorization request

info

redirect_uri?error=access_denied&message=The+resource+owner+or+authorization+server+denied+the+request.&hint=The+user+denied+the+request

If the user accepted the authorization request

info

redirect_uri?code={auth_code}

With the provided auth code you will be able to create an access token. The auth code expires after one minute.

Request the access token

With the auth code you can now request the access token.

Request

Url	https://auth.justimmo.at/access_token
Method	POST
Headers	Content-Type: application/x-www-form-urlencoded
Body	code={auth_code}&grant_type=authorization_code&client_id={your_client_id}&client_secret={your_client_secret}

Response error

{
    "error": "invalid_request",
    "message": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.",
    "hint": "Authorization code has expired"
}

Response success

{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "...",
    "refresh_token": "..."
}

Refresh code grant

The refresh code grant allows you to generate a new access token with the same payload as the access token the refresh token belongs to.

Url	https://auth.justimmo.at/access_token
Method	POST
Headers	Content-Type: application/x-www-form-urlencoded
Body	refresh_token={your_refresh_token}&grant_type=refresh_token&client_id={your_client_id}&client_secret={your_client_secret}

Response error

{
    "error": "invalid_request",
    "message": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.",
    "hint": "Refresh token has expired"
}

Response success

{
    "token_type": "Bearer",
    "expires_in": 86400,
    "access_token": "...",
    "refresh_token": "..."
}

Client credentials grant

The client credentials grant allows you to fetch an access token to access global and client specific resources. You won't have access to personal resources of users.

Url	https://auth.justimmo.at/access_token
Method	POST
Headers	Content-Type: application/x-www-form-urlencoded
Body	grant_type=client_credentials&client_id={your_client_id}&client_secret={your_client_secret}

Response error

{
    "error":"invalid_client",
    "message":"Client authentication failed"
}

Response success

{
    "token_type":"Bearer",
    "expires_in":2678400,
    "access_token": "..."
}

Using the access token

To authenticate with the resource server you must add following header to your requests

info

Authorization: Bearer {access_token}

Retrieving user and tenant id

Url	https://api.justimmo.at/oauth/user/current
Method	GET
Headers	Authorization: Bearer {access_token}

Response success

{
    "id": 1234,
    "tenant": {
        "id": 5678
    }
}