Base URL: https://{your frappe instance}

Example: https://demo.erpnext.com

OAuth2

Use the header Authorizaton: Bearer <access_token> to perform authenticated requests. You can receive a bearer token by combining the following two requests.

POST /api/method/frappe.integrations.oauth2.authorize

Get an authorization code from the user to access ERPNext on his behalf.

Params (in body):

  • client_id (string)

    ID of your OAuth2 application

  • state (string)

    Arbitrary value used by your client application to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter should be used for preventing cross-site request forgery.

  • response_type (string)

    "code"

  • scope (string)

    The scope of access that should be granted to your application.

  • redirect_uri (string)

    Callback URI that the user will be redirected to, after the application is authorized. The authorization code can then be extracted from the params.

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

Example:

curl -X POST https://{your frappe instance}/api/method/frappe.integrations.oauth2.authorize \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -H 'Accept: application/json' \
     -d 'client_id=511cb2ac2d&state=444&response_type=code&scope=all
         &redirect_uri=https%3A%2F%2Fapp.getpostman.com%2Foauth2%2Fcallback'

For testing purposes you can also pass the parameters in the URL, like this (and open it in the browser):

https://{your frappe instance}/api/method/frappe.integrations.oauth2.authorize?client_id=511cb2ac2d&state=444&response_type=code&scope=all&redirect_uri=https%3A%2F%2Fapp.getpostman.com%2Foauth2%2Fcallback

Returns:

  • HTTP Code: 200
  • text/html

    This will open the authorize page which then redirects you to the redirect_uri.

If the user clicks 'Allow', the redirect URI will be called with an authorization code in the query parameters:

https://{redirect uri}?code=plkj2mqDLwaLJAgDBAkyR1W8Co08Ud

If user clicks 'Deny' you will receive an error:

https://{redirect uri}?error=access_denied

POST /api/method/frappe.integrations.oauth2.get_token

Trade the authorization code (obtained above) for an access token.

Params (in body):

  • grant_type (string)

    "authorization_code"

  • code (string)

    Authorization code received in redirect URI.

  • client_id (string)

    ID of your OAuth2 application

  • redirect_uri (string)

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

Example:

curl -X POST https://{your frappe instance}/api/method/frappe.integrations.oauth2.get_token \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -H 'Accept: application/json' \
     -d 'grant_type=authorization_code&code=wa1YuQMff2ZXEAu2ZBHLpJRQXcGZdr
         &redirect_uri=https%3A%2F%2Fapp.getpostman.com%2Foauth2%2Fcallback&client_id=af615c2d3a'

For testing purposes you can also pass the parameters in the URL like this (and open it in the browser):

https://{your frappe instance}/api/method/frappe.integrations.oauth2.get_token?grant_type=authorization_code&code=A1KBRoYAN1uxrLAcdGLmvPKsRQLvzj&client_id=511cb2ac2d&redirect_uri=https%3A%2F%2Fapp.getpostman.com%2Foauth2%2Fcallback

Returns:

    {
        "access_token": "pNO2DpTMHTcFHYUXwzs74k6idQBmnI",
        "token_type": "Bearer",
        "expires_in": 3600,
        "refresh_token": "cp74cxbbDgaxFuUZ8Usc7egYlhKbH1",
        "scope": "all"
    }

POST /api/method/frappe.integrations.oauth2.revoke_token

Revoke token endpoint.

Params:

  • token

    Access token to be revoked.

Returns:

    {
        "message": "success"
    }

Further Reading

Please check Guides / Integration / How To Set Up Oauth to see how to create a new oAuth2 client.

Author: Raffael Meyer (raffael@alyf.de)

Next: Manipulating Documents