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

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

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

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

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
    }
}