Authorization Code Grant

Some REST API endpoints require a user context. When calling these endpoints, a user’s access token must be provided.

The OAuth 2.0 Authorization Framework standard specification can be found in The OAuth 2.0 Authorization Framework.

1. Login

Returns the login page for a user to authenticate:

Endpoint:
GET /{langCode}/auth

Headers:
Content-Type:application/x-www-form-urlencoded

Query: 
response_type=code
client_id={app’s client_id}
redirect_uri={redirect uri}
theme={dark|red|light|accessibility|any other theme from myq}

The scope parameter has to be present when requesting the authorization code from the server, otherwise, the request for a token later ends with "invalid parameter".

2. One-time access code receiving

After the login process is completed server will point the user to the provided redirect_uri with the generated access code included as url parameter.

Endpoint:
HTTP/1.1 302 Found
Headers:
Location: {redirect_uri}

Query: 
code={generated one time access code}

3. Retrieving an access token

Authentication token endpoint: POST /api/auth/token

If authentication happens, you'll receive an access token that must be provided at any other API endpoint. The scope parameter here is not required and is ignored. The redirect_uri parameter is required and must match the redirect_uri from the authorization request.

Example Request:

Endpoint:
POST /api/auth/token

Headers:
Content-Type:application/json

Query:
grant_type="authorization_code"
client_id={app client_id}
client_secret={app secret}
code={generated one time access code}
redirect_uri={redirect_uri}

Example Response:

{
	"access_token": "{your_bearer_token}",
	"token_type": "Bearer",
	"expires_in": 1800,
	"scope": "{granted scopes}"
}