The Mechanism of oAuth authorization came to replace the old method of API-keys of users. The new method will help developers solve various tasks that the old one wasn’t able to solve. Here are the main tasks that you can solve with the oAuth authorization method in amoCRM:
- Get access to the account data in which you are an administrator, using a simplified method of authorization, without redirecting. For simple tasks – simple logic.
- Get authorization and permissions from users of amoCRM to access their account data, based on permissions that you ask for.
- Register and authorize users in your application developed on the base of authorization in amoCRM, using the Sign up button in amoCRM.
- Upload a widget in the system to use in the browser.
To simplify the integration process, we developed an authorization library. At this moment we support a library developed on PHP, but, we believe, reviewing source files will give a hint to developers on that code in other languages.
What is an Integration?
To enable your application/service to send requests to the API of amoCRM, you will need to add an integration in the ‘Integrations section’ in your account. After filling out a minimalistic form, amoCRM will generate and will show the required authorization keys, which you can use in the process of authorization.
Some keys are unique for integration and will always be shown only in the account, in which you create this integration, this account will be treated as a developer account. All administrators of such accounts can edit the integration.
After creating an integration it will have two specific parameters. They will be used independently from the account, in which it will be installed: Secret key and Integration ID, which will be used during authorization.
What is a widget?
A widget is an addition to an integration and contains an archive with files that will be downloaded to the users and will run in the browser of the client. The archive has a set of images, that are required to show in various places throughout the system, set of language packs which the widget needs in order to work, and also js-files, which will run and the file manifest.json, which has the main parameters of the widget.
What is an installation?
The connection between an integration and the exact account, in which the integration was installed. Integration – is a separate object. It is connected with the developer account, in which it was developed. For an integration to get access to the account, it needs to be installed/enabled in the account.
When you enable an integration in an account, during the connection you will have a temporary identifier – An authorization code.
What is an Authorization Code?
An authorization code is required for the initial obtaining of a pair of access and refresh tokens. You can see it in the interface or through a Redirect URI if the authorization was run from the modal window for permissions. The lifespan of the code is 20 minutes. This code is not hidden, users can see it in server requests. That’s why within the oAuth 2.0 protocol it’s required to change it to the refresh and access tokens, using the keys of the apps, that only you can know.
Within the integration-account connection, there can be several Authorization codes and several Access tokens/ Refresh token links, because an integration in one account can be set by different account administrators at the same time.
What is an Access token?
This is a string of standard in JSON Web Token, which is used to send requests to amoCRM from identified users. It’s kind of an analog to the session ID. Each token has:
- User ID, which has a token connected to them
- Application ID, which has a token connected to them
- Set of actions, that the app can do
- Account ID, which has a token connected to them
The token has a limited lifespan (24 hours) and can be acquired with the help of an Authorization code or Refresh token.
What is a Refresh token?
An additional string that is acquired with the access token. The refresh token is used to refresh and update the access token, the lifespan of which is ending. This token has a lifespan of 3 months, and on each update of the access token a new refresh token is generated. Each time a session expires you will need to update both tokens and you cannot use the old key. If 3 months run out, we believe this integration as not used and the refreshed token will also run out. This means, the user who was granted access will need to be granted access again