AUTHORIZATION

API authorization

Authorizes the user on the system. All API methods can be used only after authorization.

In response to the request, upon successful authorization, in addition to the response body, the cookie file containing the session key is returned, similar to working with the WEB browser. For further requests to the API, you need to return the received cookies back. The session life time is 15 minutes.

All requests to the API come from the user whose details were used for authorization through this method. In doing so, we take into account all user rights, i.e. The API can not get more data than the user can view through the interfaces of the system. We recommend for the API to create a separate user for a more specific configuration of the rights of the connected application.

Method URL

POST/private/api/auth.php

Parameter
ParameterDescription
USER_LOGIN
require
User login. The login is e-mail.
USER_HASH
require
The user's key, which can be obtained from the user profile edit page.

The method can also accept an optional GET parameter.

ParameterDescription
type If type = json, the response will be in JSON format instead of XML
Request example
ParameterData
POST https://example.amocrm.com/private/api/auth.php
POST DATAUSER_LOGIN=example@amocrm.com&USER_HASH=c123ae456cd7891246bffb1e654abb9d
Response example
  1. <root>
  2.   <auth>true <!-- (or false in case of errors) --></auth>
  3. </root>
Example of an integration:
  1. #Array with the parameters which you need to pass via the POST API method
  2. $user=array(
  3.  'USER_LOGIN'=>'test@testmail.com', #Your login (email)
  4.  'USER_HASH'=>'7ebefd1d4741106a4daa0e0a673bba2e4dc16054' #Hash for API access (see user profile)
  5. );
  6. $subdomain='test'; #Our account is a subdomain
  7. #Form a link to request
  8. $link='https://'.$subdomain.'.amocrm.com/private/api/auth.php?type=json';
  9. /* We need to initiate a request to the server. Let's use cURL library (supplied as part of PHP). You also
  10. can
  11. use cross-platform cURL program if you don't program in PHP. */
  12. $curl=curl_init(); #Save the cURL session handle
  13. #Set the required options for cURL session
  14. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  15. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  16. curl_setopt($curl,CURLOPT_URL,$link);
  17. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  18. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($user));
  19. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  20. curl_setopt($curl,CURLOPT_HEADER,false);
  21. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  22. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  23. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  24. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  25. $out=curl_exec($curl); #Initiate a request to the API and store the response in a variable
  26. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE); #Get HTTP response code of the server
  27. curl_close($curl); #End the cURL session
  28. /* We can now process the response received from the server. This example. You can process the data in your own way. */
  29. $code=(int)$code;
  30. $errors=array(
  31.   301=>'Moved permanently',
  32.   400=>'Bad request',
  33.   401=>'Unauthorized',
  34.   403=>'Forbidden',
  35.   404=>'Not found',
  36.   500=>'Internal server error',
  37.   502=>'Bad gateway',
  38.   503=>'Service unavailable'
  39. );
  40. try
  41. {
  42.   #If the response code is not 200 or 204 - return an error message
  43. if($code!=200 && $code!=204)
  44.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  45. }
  46. catch(Exception $E)
  47. {
  48.   die( ''Error: ' .$E->getMessage().PHP_EOL. 'Error code: ' .$E->getCode());
  49. }
  50. /*
  51. The data is obtained in JSON format, therefore, to obtain readable data,
  52. we'll have to translate the answer into a PHP-friendly format
  53.  */
  54. $Response=json_decode($out,true);
  55. $Response=$Response['response'];
  56. if(isset($Response['auth'])) #authorization flag is available in the 'auth' property
  57. return 'Authorization succeeded' ;
  58. return 'Authorization failed' ;
Error code HTTP code Description
110 401 Unauthorized General authorization error. Incorrect login or password
111 401 Unauthorized Occurs after several unsuccessful authorization attempts. In this case, you need to log in to your account through the browser by entering the captcha code.
112 401 Unauthorized Occurs when the user is turned off in the "Users and Rights" account settings or is not in the account.
113 403 Forbidden Access to this account is prohibited from your IP address. Occurs when the filtering of access to the API by the "whitelist of IP addresses" is enabled in the account security settings.
101 401 Unauthorized Occurs in the case of a request to a non-existent account (subdomain).
401 401 Unauthorized Not Authorized. There is no account information on the server. You need to make a request to another server on the transmitted IP.
401 Not Authorized (there are no account data on the server)

Occurs when the account is registered on one server, and the request goes to another server that does not have the data of this account. Most often it happens when the account is registered on one server, for example, on amocrm.com, and the request to the API goes to another server, for example on amocrm.com.
To ensure the smooth operation of the project, we use not one but several servers, so there are situations when the response can return HTTP code 401 and error_code 401, even to the correct authorization data. At this point in the response, the correct IP of the server to which the request should be repeated is also transmitted. Note that in this case, the client must be given the same hostname that was used when requesting 401 for the correct operation of the certificates.

Response example
  1. {
  2.     response: {
  3.         error: "401 Not Authorized"
  4.         ip: "95.213.174.147"
  5.         domain: "example.amocrm.com"
  6.         auth: false
  7.         server_time: 1444448888
  8.         error_code: "401"
  9.     }
  10. }
See also

ERROR CODES API