Version 2 (OAuth2)

Authorization flow

The API version 2 implements the OAuth2 authorization framework, enabling secure authentication and authorization to access its resources. This flow has been developed specifically for the Make Academy Custom Apps Development course, aiming to simulate a real-world authentication and authorization process.

Every developer can integrate Custom App Academy API V2 by obtaining up to one app access that involves registration of their application and obtaining client credentials.

To obtain the necessary client credentials (client ID and secret), you can submit the form. If you have previously submitted the form for API version 1, you should already have received the credentials to API version 2 via email.

To provide a realistic user authorization experience, API version 2 includes a feature where users can select the specific account they want to connect with the application. This mimics the behavior seen in real-world applications.

Selection of the account authorize

Each app user (John Doe/Jane Black) can have only one active connection. If you generate a new connection, the existing one will be removed.

Step one: Redirect a user to your app

Redirect the user to authorize endpoint. This will prompt the user to allow your application to access the Custom App Academy API on their behalf. You need the user to allow the connect scope to successfully authorize access. To obtain the code parameter to authorize token request, set the response_type to code.

Endpoint to authorize access.

get

This endpoint enables authorization of your access to API.

Required scopes

This endpoint requires the following scopes:

• : allows connection to resources

Authorizations

accessCode

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Query parameters

scopestringRequiredExample: connect

client_idstringRequired

redirect_uristringRequiredExample: https://www.integromat.com/oauth/cb/app

response_typestringRequiredExample: code

Responses

200

OK

application/json

codestringOptional

400

Bad Request

404

Not Found

501

Not Supported

get

/authorize

HTTPcURLJavaScriptPython

GET /api/v2/authorize?scope=text&client_id=text&redirect_uri=text&response_type=text HTTP/1.1
Host: app-academy.make.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "code": "text"
}

Step two: Handle the callback request

Once a user decides to allow or disallow your application access to their account, Custom App Academy will redirect them to the OAuth2 redirect URL that you set when submitting your form.

If there was an error processing the request, the response will contain an error.message parameter. If the request was successful, the response will contain code parameter.

Step three: Retrieve an access token and refresh token

Use your application client_id and client_secret together with code from the previous step to issue a request to token endpoint. You must use the same redirect URL in the token request and authorization_code grant type.

A successful request will respond with access_token, expires-in, refresh_token and refresh_expires_in parameters. expires-in and refresh_expires_in values are in minutes.

Endpoint to retrieve token.

post

This endpoint retrieves the token.

Required scopes

This endpoint requires the following scopes:

• : allows connection to resources

Authorizations

accessCode

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

application/json

codestringRequired

client_idstringRequired

grant_typestringRequiredExample: authorization_code

redirect_uristringRequiredExample: https://www.integromat.com/oauth/cb/app

client_secretstringRequired

Responses

200

OK

application/json

access_tokenstringOptional

expires_innumberOptionalExample: 5

refresh_tokenstringOptional

refresh_expires_innumberOptionalExample: 5

400

Bad Request

404

Not Found

501

Not Supported

post

/token

HTTPcURLJavaScriptPython

POST /api/v2/token HTTP/1.1
Host: app-academy.make.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 148

{
  "code": "text",
  "client_id": "text",
  "grant_type": "authorization_code",
  "redirect_uri": "https://www.integromat.com/oauth/cb/app",
  "client_secret": "text"
}

{
  "access_token": "text",
  "expires_in": 5,
  "refresh_token": "text",
  "refresh_expires_in": 5
}

Step four: Make an API request

After obtaining the access token, you can send requests to App Academy API that contain the authorization header in this format: Bearer {access_token}.

Endpoint to retrieve info about the connected account.

get

This endpoint retrieves info about the connected account.

Required scopes

This endpoint requires the following scopes:

• : allows connection to resources

Authorizations

accessCode

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Header parameters

authorizationstringRequiredExample: Bearer [accessToken]

Responses

200

OK

application/json

idstringOptionalExample: d1b03e513fbc5881651d6c149fd259506f975ae1

userstringOptionalExample: Jane Doe

401

Not Authorized.

403

Missing Scope.

get

/info

HTTPcURLJavaScriptPython

GET /api/v2/info HTTP/1.1
Host: app-academy.make.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
authorization: text
Accept: */*

{
  "id": "d1b03e513fbc5881651d6c149fd259506f975ae1",
  "user": "Jane Doe"
}

Step five: Refresh the access token

The API provides the expires_in parameter in the token response to determine if the user's access token has expired. If it has, use the refresh endpoint to retrieve a new access token and refresh token. expires-in and refresh_expires_in values are in minutes. To obtain a new access token and refresh token, the refresh token must not be expired!

Endpoint to retrieve a new refresh token.

post

This endpoint retrieves the refresh token.

Required scopes

This endpoint requires the following scopes:

• : allows connection to resources

Authorizations

accessCode

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Body

application/json

client_idstringOptional

grant_typestringOptionalExample: refresh_token

client_secretstringOptional

refresh_tokenstringOptional

Responses

200

OK

application/json

access_tokenstringOptional

expires_innumberOptionalExample: 5

refresh_tokenstringOptional

refresh_expires_innumberOptionalExample: 5

400

Bad Request

404

Not Found

501

Not Supported

post

/refresh

HTTPcURLJavaScriptPython

POST /api/v2/refresh HTTP/1.1
Host: app-academy.make.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "client_id": "text",
  "grant_type": "refresh_token",
  "client_secret": "text",
  "refresh_token": "text"
}

{
  "access_token": "text",
  "expires_in": 5,
  "refresh_token": "text",
  "refresh_expires_in": 5
}

Step six: Access invalidation

If the user wants to invalidate the access of your app to Custom App Academy API, use the invalidate endpoint.

Endpoint to invalidate the access token.

get

This endpoint invalidates the access token.

Required scopes

This endpoint requires the following scopes:

• : allows connection to resources

Authorizations

accessCode

OAuth2authorizationCodeRequired

Authorization URL: Token URL:

Header parameters

authorizationstringRequiredExample: Bearer [accessToken]

Responses

204

OK

401

Not Authorized.

get

/invalidate

HTTPcURLJavaScriptPython

GET /api/v2/invalidate HTTP/1.1
Host: app-academy.make.com
Authorization: Bearer YOUR_OAUTH2_TOKEN
authorization: text
Accept: */*

No content

Scopes

API Version 2 provides integration with scopes. Scopes provide a granular level of access control and ensure that users can only access the specific resources they need. The following scopes are supported:

Endpoint	Scope
authorize	connect
any GET endpoint*	read
any POST/PUT/PATCH ednpoint	write
any DELETE endpoint	delete

*except for /info endpoint.

Endpoints

In API version 2, all the endpoints available in API version 1 are fully supported. To make API calls in version 2, you need to use the URL for API version 2 as well as to ensure proper authorization and scope management by following the instructions provided above.

Version 1 (API key)