API Client
 All Classes Functions Pages
Authentication

1CRM API calls must include authentication information. The API supports two authentication methods: Basic and OAuth 2.0.

Basic authentication

OAuth 2.0 authentication

Basic authentication

HTTP Basic authentication is the simplest form of authentication supported by 1CRM API. It uses 1CRM user name and password, and transmits them in HTTP request headers. This simplicity is the only advantage of this authentication method. Username and password are sent in cleartext with each request. Whenever possible, you should prefer OAuth 2.0.

To use basic authentication, you first create an instance of OneCRM\APIClient\Authentication\Basic, passing user name and password to constructor. Then create an API client using this authentication object. The example below uses the URL of 1CRM demo site, you should use the URL of your 1CRM system instead.

use OneCRM\APIClient;
$auth = new Authentication\Basic('admin', 'admin');
$client = new APIClient\Client('https://demo.1crmcloud.com/api.php', $auth);
// now $client is ready to make API requests
Note
Basic authentication for API is disabled by default. If you want to use it, you have to enable it first, using 1CRM administration interface.

OAuth 2.0 authentication

This authentication method uses access tokens. Before making requests, you need to obtain an access toke from the API.

In order to make calls to the 1CRM API using OAuth 2.0, you need to register an application, or API client. Registered clients are assigned a unique Client ID (client_id) and a unique Client Secret (client_secret). Make sure to store the Client Secret securely.

1CRM supports 2 types of API clients: public and private.

Private API clients can be registered by 1CRM administrator, and are intended for use by your organization only. Public API clients are managed by 1CRM Corp., and represent 3rd party applications. If you are developing an application that can be potentially useful for all 1CRM customers, you should apply for a public API client.

Client ID and Client Secret for private clients are available from 1CRM admin interface. For public clients, 1CRM will provide Client ID and Client Secret after creating your API CLient.

Resource owners

One of roles defined by OAuth 2.0 Authorization Framework is Resource Owner:

An entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end-user.

Naturally, in 1CRM, its users are resource owners. API client can be granted access on behalf of a 1CRM user. But there are many cases, when it is also desirable to allow Contacts to authenticate themselves: using 1CRM as single sign-on server, customer portals, etc.

1CRM defines two types of Resource Owners: User and Contact. Depending on type of resource owner you want to authenticate, you use different endpoints. Note that Contact access token only provides access to Contact's own information such as name, email address and telephone number.

Scopes

When requesting access to protected resources, API client can specify the scope of request. 1CRM supports 3 scopes:

For Resource Owner of Contact type, only profile scope is allowed. read and write scopes are subject to limitations set by 1CRM administrator using 1CRM ACL system.

If you do not specify a scope in authorization request, profile will be used by default.

Obtaining access token

1CRM API Client library provides several authorization flows

Warning
Before using an authorization flow, make sure it is enabled in 1CRM admin interface for the Client ID you are using.

Authorization flow parameters

When starting an authorization flow, you first have to prepare an associative array with following options:

Authorization Code grant

This flow is a two-step process. First, you make the user visit a special URI where the user logs into 1CRM and grants access to your application. After access is granted, the user is redirected to redirect URI that you specify, and authorization code is passed in URI query parameter. Script at that redirect URI now can obtain an access token.

use OneCRM\APIClient;
$options = [
'client_id' => '123456789-xxx-whatever',
'client_secret' => 'top secret',
'redirect_uri' => 'https://mydomain.com/redirect.php',
'scope' => 'read write profile',
];
$flow = new APIClient\AuthorizationFlow('https://demo.1crmcloud.com/api.php', $options);
$url = $flow->init('authorization_code');
header('Location: ' . $url);
// or you can make the library to do the redirect for you by passing true
// as second argument to AuthorizationFlow::init()
$flow->init('authorization_code', true);

After the user returns to redirect URI, you can obtain an access token from the API:

use OneCRM\APIClient;
// should be same options as used when calling AuthorizationFlow::init()
$options = [
'client_id' => '123456789-xxx-whatever',
'client_secret' => 'top secret',
'redirect_uri' => 'https://mydomain.com/redirect.php',
'scope' => 'read write profile',
];
$flow = new APIClient\AuthorizationFlow('https://demo.1crmcloud.com/api.php', $options);
$access_token = $flow->finalize();
$auth = new Authentication\OAuth($access_token);
$client = new APIClient\Client('https://demo.1crmcloud.com/api.php', $auth);
// now $client is ready to make API requests

Resource Owner Password Credentials Grant

This grant provides great user experience for web applications and native mobile applications, because it does not require the user to be redirected to 1CRM for password entry. This grant is only available for private API clients.

use OneCRM\APIClient;
$options = [
'client_id' => '123456789-xxx-whatever',
'client_secret' => 'top secret',
'scope' => 'read write profile',
'username' => 'admin',
'password' => 'admin',
];
$flow = new APIClient\AuthorizationFlow('https://demo.1crmcloud.com/api.php', $options);
$access_token = $flow->init('password');
$auth = new Authentication\OAuth($access_token);
$client = new APIClient\Client('https://demo.1crmcloud.com/api.php', $auth);
// now $client is ready to make API requests

Client Credentials Grant

To enable this grant, 1CRM administrator assigns a user to API client using 1CRM admin interface. After obtaining access token, API client can make requests to the API on behalf of that user. This grant is only available for Resource Owner of User type.

use OneCRM\APIClient;
// should be same options as used when calling AuthorizationFlow::init()
$options = [
'client_id' => '123456789-xxx-whatever',
'client_secret' => 'top secret',
'scope' => 'read write profile',
];
$flow = new APIClient\AuthorizationFlow('https://demo.1crmcloud.com/api.php', $options);
$access_token = $flow->init('client_credentials');
$auth = new Authentication\OAuth($access_token);
$client = new APIClient\Client('https://demo.1crmcloud.com/api.php', $auth);
// now $client is ready to make API requests

Resfreshing access tokens

Access tokens have a limited lifetime. 1CRM administator can configure access token expiration time. After access token has expired, it cannot be used to access the API any more. To continue using the API, you must refresh an expired access token. To understand how token refreshing works, lets have a look at access token structure first:

use OneCRM\APIClient;
$options = [
'client_id' => '123456789-xxx-whatever',
'client_secret' => 'top secret',
'scope' => 'read write profile',
'username' => 'admin',
'password' => 'admin',
];
$flow = new APIClient\AuthorizationFlow('https://demo.1crmcloud.com/api.php', $options);
$access_token = $flow->init('password');
echo json_encode($access_token, JSON_PRETTY_PRINT);
{
"token_type": "Bearer",
"expires_in": 86399,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6ImI3NzBjZjQzODcxYTRlYWJmODg3ZmMwYmQzOTA5ZTBkZjY2M2U3MjEwNzE4YWVmYjIzNzUxNmNhMzE3YTgzYTk0ZGFlMTE4NTk1NWE3ZGUyIn0.eyJhdWQiOiIxMmVjYjI1Yy0zNWZiLWQyOWUtYmI2Ni01YTkwM2EwNDhiMDYiLCJqdGkiOiJiNzcwY2Y0Mzg3MWE0ZWFiZjg4N2ZjMGJkMzkwOWUwZGY2NjNlNzIxMDcxOGFlZmIyMzc1MTZjYTMxN2E4M2E5NGRhZTExODU5NTVhN2RlMiIsImlhdCI6MTUxOTQ4MzcyNCwibmJmIjoxNTE5NDgzNzI0LCJleHAiOjE1MTk1NzAxMjMsInN1YiI6IlVzZXJzOjEiLCJzY29wZXMiOlsicmVhZCIsIndyaXRlIiwicHJvZmlsZSJdfQ.AUKqkoUPBDWfbX69JLoiwZRhxEox_hXbLXSaO65CFecpsi9iTn-pfNUfBUs7rlHNv1uZis2h3Ia8ZiMOdobLMWlqh6SPnvIgA82J_0BVPDVoSijxF2TZ2v-kKq0KsbBAZcJhMBMw2WTP2Wmcf9m4A92kkKUmmwOvF9B_7WLjZ-hw1VMLLdO4rIWXimvwH0Y6-8Tvc6N2PCp5U2DYPaKxZ1jXgNI3ldJz1nJMmstK3d9IBTPV3SsKdWFHJn48Md9DBGBEy6E5oiCJqj17wimqjbgPzLo3KiR7EcZ5bid7jcR3gXfwFyE3_7nmMkdyoY8nAf6jVnkk72njH_iEjBobEHFPb2WovD8JWMwaEqCQjBVMz9K6UVy31v7Mbo1ulUIiCL5-qqXOIMQ9EfUGCqHtkcMKMZdD4DKeGGc2LJhBCwABUETHtbwab9uMAPb7OFAQUMMNewNidumc7pLRYoUajRdSyt_C_XZ2B8Jh2ASAYoAVXSYkL_6CbjBSMcf6saXp9_QGiujk1LsJpoK6GuKgvYRR3QI8lUsj_SiwamLgghGCe_l_71OezneystWxZ992qTKqEY2_lGtLDT1DggybsyC6hEmxJ_FIkI00mKXoTlL2lQKYc6eMpys6hJyJsF6oTuYPDo3CKsdHjDGxjBVog3wU8dEN3r4Uhe0_5ni-8Cw",
"refresh_token": "pXppRl+5sqtdImvH+TTZHzcPXaRFDTkf2\/p0T+VPygAcg7JF5N7ZCR5NdIyhdU+IOsfv9wdCohrk6LviVKlRdlT9MLh\/x6aOU3bYXv1vriIakgiM5KGiRIHE\/yxfYbndSf6cTYu4xCPpZSeALu8dpg2r43fK9y9Gl70u2wQtTRARp9cnqMSgzh9wHRRBrtcqOl9\/hlekBZ9\/VMwHQ59s+oVJBsYIryHtUGoVh8n1TkraYl7hPPitHFfnp7pjXSGCdBbEeZpXemeVLjNOmfEIdvoZA5yADJiL3jAvM+8iNRoLPi7Xx0dhITgxf9fcNeK834cWop6WHnhpB\/PpEAOivKnn3+kmS318rsTrIGgbtScqAZICXmjll5Os7zpz\/zUVxWlDOqEzL1IrGvuvjE5JWuVHpeWv9AyoyTUArYwlPQCoH2o\/frXXUiMWI34+Ffw1rOFFkY63D2SEcmNNXXGfyn70Qe6AEmPQoUbVdvnsIikF9J+zkcGg\/3z1FXRfcp7M9CVDnkzA\/osjIwQrHNBvRIoRizouTnRDesg2Au209pIxJUSbCgQeKlve\/5LnNhRK9BS527ikq79rkbxYufTc\/wg7t5pORCh48RV8ScIX+zWllkDItDkDH666o61bVw7vOkXw4Z5NVyNEoon\/WfZMJWTGFJOU681PcR4L0YcHYHU="
}

You can use expires_in fields to calculate the time when the token expires (the value is in seconds). Any time before the expriration time, you can use the refresh token to obtain a new access token:

use OneCRM\APIClient;
$options = [
'client_id' => '123456789-xxx-whatever',
'client_secret' => 'top secret',
'scope' => 'read write profile',
];
$flow = new APIClient\AuthorizationFlow('https://demo.1crmcloud.com/api.php', $options);
$access_token = stored_access_token(); // previously obtained access token
$new_token = $flow->refreshToken($access_token['refresh_token']);
echo json_encode($new_token, JSON_PRETTY_PRINT);