POST /Api/access_tokenAvailable Grant Types
Configure Authentication: Obtaining A Session
The SuiteCRM API requires that a client has an active session to consume the API. Sessions are acquired by authenticating with the OAuth 2 Server, using one of the available grant types.
Configure Grant Types
Before you can consume the API, you must first configure SuiteCRM to grant access to a client. SuiteCRM 7.10 provides an administrative panel, through which you can add clients and revoke tokens. To configure the grant types, select the admin panel, and then select OAuth2 Clients and Tokens:
Available Grant Types
| SuiteCRM Version | Available Grant Types |
|---|---|
7.10.0 |
Password Grant, Refresh Token Grant |
7.10.2 |
Password Grant, Client credentials Grant, Refresh Token Grant |
7.15.0 |
Password Grant, Client credentials Grant, Refresh Token Grant, Authorization Code Grant |
Client Credentials Grant
A client credentials grant is the simplest of all of the grants types, this grant is used to authenticate a machine or service. Select new client credentials client:
Begin configuring the grant:
| Field | Description |
|---|---|
Name |
This makes it easy to identify the client. |
Secret |
Defines the client_secret which is posted to the server during authentication. |
Is Confidential |
A confidential client is an application that is capable of keeping a client password confidential to the world. |
Associated User |
Limits the client access to CRM, by associating the client with the security privileges of a user. |
The 'secret' will be hashed when saved, and will not be accessible later. The 'id' is created by SuiteCRM and will be visible once the client is saved.
Authentication with Client Credentials
Required parameters
| param | value |
|---|---|
grant_type |
client_credentials |
client_id |
ExampleClientName |
client_secret |
ExampleSecretPassword |
Example Request (PHP):
$ch = curl_init();
$header = array(
   'Content-type: application/vnd.api+json',
   'Accept: application/vnd.api+json',
);
$postStr = json_encode(array(
   'grant_type' => 'client_credentials',
   'client_id' => '3D7f3fda97-d8e2-b9ad-eb89-5a2fe9b07650',
   'client_secret' => 'client_secret',
));
$url = 'https://path-to-instance/Api/access_token';
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postStr);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$output = curl_exec($ch);Example Response:
{
  "token_type":"Bearer",
  "expires_in":3600,
  "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjdkOTEyODNhMjc1NDdkNDRlMzNmOTc5ZjVmMGRkYzQwNzg1ZGY5NGFhMWI5MDVlZGNmMzg3NWIxYjJkZDMzNDljZWEyNjZhMTQ2OTE5OWIzIn0.eyJhdWQiOiJzdWl0ZWNybV9jbGllbnQiLCJqdGkiOiI3ZDkxMjgzYTI3NTQ3ZDQ0ZTMzZjk3OWY1ZjBkZGM0MDc4NWRmOTRhYTFiOTA1ZWRjZjM4NzViMWIyZGQzMzQ5Y2VhMjY2YTE0NjkxOTliMyIsImlhdCI6MTUxODE5NTEwMiwibmJmIjoxNTE4MTk1MTAyLCJleHAiOjE1MTgxOTg3MDIsInN1YiI6IjEiLCJzY29wZXMiOltdfQ.EVGuRisoMxSIZut3IWtgOYISw8lEFSZgCWYCwseLEfOuPJ8lRMYL4OZxhu9gxJoGF0nj3yc6SYDPxovrsoj8bMoX38h4krMMOHFQLoizU0k2wAceOjZG1tWKPhID7KPT4TwoCXbb7MqAsYtVPExH4li7gSphJ8wvcWbFdS5em89Ndtwqq3faFtIq6bv1R4t0x98HHuT7sweHUJU40K9WQjbAfIOk8f5Y6T2wassN2wMCBB8CC6eUxLi14n2D6khHvkYvtPbXLHpXSHZWvEhqhvjAeSR5MmMrAth9WDSWUx7alO-ppsZpi8U7-g9Be5p6MRatc25voyTI2iTYbx02FQ",
}| token_type | the Bearer token value |
|---|---|
expires_in |
an integer representing the TTL of the access token |
access_token |
a JWT signed with the authorization server’s private key. It is required that you include this in the HTTP headers, each time you make a request to the API |
You can store the bearer token in a database and use in your requests like this:
Example
$header = array(
   'Content-type: application/vnd.api+json',
   'Accept: application/vnd.api+json',
   'Authorization: Bearer ' . $your_saved_access_token
);Password Grant
A password grant is used for allow users to log into SuiteCRM with a username and a password. Select new password client:
Begin configuring grant:
Name |
This makes it easy to identify the client. |
Secret |
Defines the client_secret which is posted to the server during authentication. |
Is Confidential |
A confidential client is an application that is capable of keeping a client password confidential to the world. |
The 'secret' will be hashed when saved, and will not be accessible later. The 'id' is created by SuiteCRM and will be visible once the client is saved.
Authentication with Password Grant
POST /Api/access_tokenRequired parameters
| param | value |
|---|---|
grant_type |
password |
client_id |
ExampleClientName |
client_secret |
ExampleSecretPassword |
username |
admin |
password |
secret |
Please change the values in bold to match your chosen authentication details.
Example Request (PHP):
$ch = curl_init();
$header = array(
   'Content-type: application/vnd.api+json',
   'Accept: application/vnd.api+json',
);
$postStr = json_encode(array(
   'grant_type' => 'password',
   'client_id' => '3D7f3fda97-d8e2-b9ad-eb89-5a2fe9b07650',
   'client_secret' => 'client_secret',
   'username' => 'admin',
   'password' => 'admin',
));
$url = 'https://path-to-instance/Api/access_token';
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postStr);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$output = curl_exec($ch);Example Response:
{
  "token_type":"Bearer",
  "expires_in":3600,
  "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjdkOTEyODNhMjc1NDdkNDRlMzNmOTc5ZjVmMGRkYzQwNzg1ZGY5NGFhMWI5MDVlZGNmMzg3NWIxYjJkZDMzNDljZWEyNjZhMTQ2OTE5OWIzIn0.eyJhdWQiOiJzdWl0ZWNybV9jbGllbnQiLCJqdGkiOiI3ZDkxMjgzYTI3NTQ3ZDQ0ZTMzZjk3OWY1ZjBkZGM0MDc4NWRmOTRhYTFiOTA1ZWRjZjM4NzViMWIyZGQzMzQ5Y2VhMjY2YTE0NjkxOTliMyIsImlhdCI6MTUxODE5NTEwMiwibmJmIjoxNTE4MTk1MTAyLCJleHAiOjE1MTgxOTg3MDIsInN1YiI6IjEiLCJzY29wZXMiOltdfQ.EVGuRisoMxSIZut3IWtgOYISw8lEFSZgCWYCwseLEfOuPJ8lRMYL4OZxhu9gxJoGF0nj3yc6SYDPxovrsoj8bMoX38h4krMMOHFQLoizU0k2wAceOjZG1tWKPhID7KPT4TwoCXbb7MqAsYtVPExH4li7gSphJ8wvcWbFdS5em89Ndtwqq3faFtIq6bv1R4t0x98HHuT7sweHUJU40K9WQjbAfIOk8f5Y6T2wassN2wMCBB8CC6eUxLi14n2D6khHvkYvtPbXLHpXSHZWvEhqhvjAeSR5MmMrAth9WDSWUx7alO-ppsZpi8U7-g9Be5p6MRatc25voyTI2iTYbx02FQ",
  "refresh_token":"def50200d2fb757e4c01c333e96c827712dfd8f3e2c797db3e4e42734c8b4e7cba88a2dd8a9ce607358d634a51cadd7fa980d5acd692ab2c7a7da1d7a7f8246b22faf151dc11a758f9d8ea0b9aa3553f3cfd3751a927399ab964f219d086d36151d0f39c93aef4a846287e8467acea3dfde0bd2ac055ea7825dfb75aa5b8a084752de6d3976438631c3e539156a26bc10d0b7f057c092fce354bb10ff7ac2ab5fe6fd7af3ec7fa2599ec0f1e581837a6ca2441a80c01d997dac298e1f74573ac900dd4547d7a2a2807e9fb25438486c38f25be55d19cb8d72634d77c0a8dfaec80901c01745579d0f3822c717df21403440473c86277dc5590ce18acdb1222c1b95b516f3554c8b59255446bc15b457fdc17d5dcc0f06f7b2252581c810ca72b51618f820dbb2f414ea147add2658f8fbd5df20820843f98c22252dcffe127e6adb4a4cbe89ab0340f7ebe8d8177ef382569e2aa4a54d434adb797c5337bfdfffe27bd8d5cf4714054d4aef2372472ebb4"
}| token_type | the Bearer token value |
|---|---|
expires_in |
an integer representing the TTL of the access token |
access_token |
a JWT signed with the authorization server’s private key. It is required that you include this in the HTTP headers, each time you make a request to the API |
refresh_token |
an encrypted payload that can be used to refresh the access token when it expires. |
You can store the bearer token in a database and use in your requests like this:
Example
$header = array(
   'Content-type: application/vnd.api+json',
   'Accept: application/vnd.api+json',
   'Authorization: Bearer ' . $your_saved_access_token
);Refresh Token Grant
A refresh token grant is used if you already have a refresh token generated from password grant. It is used to get a new access token.
"grant_type": "refresh_token", "client_id": "Client Id", "client_secret": "Client Secret", "refresh_token": "refresh token" (returned with password grant)
Getting Access Token using Refresh Grant
POST /Api/access_tokenRequired parameters
| param | value |
|---|---|
grant_type |
refresh_token |
client_id |
Client ID |
client_secret |
Client Secret |
refresh_token |
refresh token |
Please change the values in bold to match your chosen authentication details. ß .Example Request (PHP):
$ch = curl_init();
$header = array(
   'Content-type: application/vnd.api+json',
   'Accept: application/vnd.api+json',
);
$postStr = json_encode(array(
   'grant_type' => 'refresh_token',
   'client_id' => '3D7f3fda97-d8e2-b9ad-eb89-5a2fe9b07650',
   'client_secret' => 'client_secret',
   'refresh_token' => 'refresh_token',
));
$url = 'https://path-to-instance/Api/access_token';
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postStr);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$output = curl_exec($ch);Example Response:
{
  "token_type":"Bearer",
  "expires_in":3600,
  "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjdkOTEyODNhMjc1NDdkNDRlMzNmOTc5ZjVmMGRkYzQwNzg1ZGY5NGFhMWI5MDVlZGNmMzg3NWIxYjJkZDMzNDljZWEyNjZhMTQ2OTE5OWIzIn0.eyJhdWQiOiJzdWl0ZWNybV9jbGllbnQiLCJqdGkiOiI3ZDkxMjgzYTI3NTQ3ZDQ0ZTMzZjk3OWY1ZjBkZGM0MDc4NWRmOTRhYTFiOTA1ZWRjZjM4NzViMWIyZGQzMzQ5Y2VhMjY2YTE0NjkxOTliMyIsImlhdCI6MTUxODE5NTEwMiwibmJmIjoxNTE4MTk1MTAyLCJleHAiOjE1MTgxOTg3MDIsInN1YiI6IjEiLCJzY29wZXMiOltdfQ.EVGuRisoMxSIZut3IWtgOYISw8lEFSZgCWYCwseLEfOuPJ8lRMYL4OZxhu9gxJoGF0nj3yc6SYDPxovrsoj8bMoX38h4krMMOHFQLoizU0k2wAceOjZG1tWKPhID7KPT4TwoCXbb7MqAsYtVPExH4li7gSphJ8wvcWbFdS5em89Ndtwqq3faFtIq6bv1R4t0x98HHuT7sweHUJU40K9WQjbAfIOk8f5Y6T2wassN2wMCBB8CC6eUxLi14n2D6khHvkYvtPbXLHpXSHZWvEhqhvjAeSR5MmMrAth9WDSWUx7alO-ppsZpi8U7-g9Be5p6MRatc25voyTI2iTYbx02FQ",
  "refresh_token":"def50200d2fb757e4c01c333e96c827712dfd8f3e2c797db3e4e42734c8b4e7cba88a2dd8a9ce607358d634a51cadd7fa980d5acd692ab2c7a7da1d7a7f8246b22faf151dc11a758f9d8ea0b9aa3553f3cfd3751a927399ab964f219d086d36151d0f39c93aef4a846287e8467acea3dfde0bd2ac055ea7825dfb75aa5b8a084752de6d3976438631c3e539156a26bc10d0b7f057c092fce354bb10ff7ac2ab5fe6fd7af3ec7fa2599ec0f1e581837a6ca2441a80c01d997dac298e1f74573ac900dd4547d7a2a2807e9fb25438486c38f25be55d19cb8d72634d77c0a8dfaec80901c01745579d0f3822c717df21403440473c86277dc5590ce18acdb1222c1b95b516f3554c8b59255446bc15b457fdc17d5dcc0f06f7b2252581c810ca72b51618f820dbb2f414ea147add2658f8fbd5df20820843f98c22252dcffe127e6adb4a4cbe89ab0340f7ebe8d8177ef382569e2aa4a54d434adb797c5337bfdfffe27bd8d5cf4714054d4aef2372472ebb4"
}| token_type | the Bearer token value |
|---|---|
expires_in |
an integer representing the TTL of the access token |
access_token |
a JWT signed with the authorization server’s private key. It is required that you include this in the HTTP headers, each time you make a request to the API |
refresh_token |
an encrypted payload that can be used to refresh the access token when it expires. |
Authorization Code Grant
An Authorization Code grant is used by web and mobile applications to obtain an access token on behalf of a user. The client redirects the user to the authorization server to authenticate and approve access; the server returns an authorization code to the client’s redirect URI. The client then exchanges that code at the token endpoint for an access token.
Configuring the Authorization Code Grant client
To setup Authorization Code grant, start by creating a new client. For that go to Administration > OAuth2 Clients and Tokens. To create the new Authorization Code client click "New Authorization Client". Then set the following inputs:
-
name
-
secret
-
is confidential
-
redirect uri (e.g. https://path-to-instance/)
Granting Authorization
Example Request:
GET Api/authorize?response_type=code&client_id=15e14434-5ea5-3290-34da-68cbf187687a&https%3A%2F%2Fpath-to-instance%2Fsuite8%2Fdev%2Fpublic%2FIn response a modal window opens asking for the user to authenticate and approve access, which is done by the following request
Example Request:
https://<path-to-instance>/index.php?module=OAuth2AuthCodes&action=authorize&response_type=code&client_id=15e14434-5ea5-3290-34da-68cbf187687a&redirect_uri=https%3A%2F%2Fpath-to-instance%2Fsuite8%2Fdev%2Fpublic%2F
When the user approves access, they will be redirected to the redirect_uri with an authorization code appended as a query parameter.
Example Redirect:
https://php82.sa.local/suite8/dev/public/?code=def502006abb4718484c71e575fe6607de4fbd0369da2c490bafc44d.....This code should be used on the following request to obtain an access token.
|
Note
|
The authorization code can only be used once. |
If the user approved always the code will still exist on the db but marked as revoked. Codes that were approved just once will be deleted from the db after use.
Getting Access Token using Authorization Code Grant
After obtaining the authorization code, you can exchange it for an access token by making the following request:
POST Api/access_token
Request Body:
grant_type: "authorization_code"
code: "def502009ebbbdbbc84dd2bbc0d....."
redirect_uri: "https://path-to-instance/"Required parameters
| param | value |
|---|---|
grant_type |
authorization_code |
code |
Authorization Code |
redirect_uri |
Redirect URI |
Please change the values in bold to match your chosen authentication details.
Example Request (PHP):
$ch = curl_init();
$header = array(
   'Content-type: application/vnd.api+json',
   'Accept: application/vnd.api+json',
);
$postStr = json_encode(array(
   'grant_type' => 'authorization_code',
   'code' => 'def502005559e4e1a06f7732d7ed3f2892274c85f9931a79b7....',
   'redirect_uri' => 'https://path-to-instance',
));
$url = 'https://path-to-instance/Api/access_token';
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $postStr);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
$output = curl_exec($ch);Example Response:
{
  "token_type":"Bearer",
  "expires_in":3600,
  "access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjdkOTEyODNhMjc1NDdkNDRlMzNmOTc5ZjVmMGRkYzQwNzg1ZGY5NGFhMWI5MDVlZGNmMzg3NWIxYjJkZDMzNDljZWEyNjZhMTQ2OTE5OWIzIn0.eyJhdWQiOiJzdWl0ZWNybV9jbGllbnQiLCJqdGkiOiI3ZDkxMjgzYTI3NTQ3ZDQ0ZTMzZjk3OWY1ZjBkZGM0MDc4NWRmOTRhYTFiOTA1ZWRjZjM4NzViMWIyZGQzMzQ5Y2VhMjY2YTE0NjkxOTliMyIsImlhdCI6MTUxODE5NTEwMiwibmJmIjoxNTE4MTk1MTAyLCJleHAiOjE1MTgxOTg3MDIsInN1YiI6IjEiLCJzY29wZXMiOltdfQ.EVGuRisoMxSIZut3IWtgOYISw8lEFSZgCWYCwseLEfOuPJ8lRMYL4OZxhu9gxJoGF0nj3yc6SYDPxovrsoj8bMoX38h4krMMOHFQLoizU0k2wAceOjZG1tWKPhID7KPT4TwoCXbb7MqAsYtVPExH4li7gSphJ8wvcWbFdS5em89Ndtwqq3faFtIq6bv1R4t0x98HHuT7sweHUJU40K9WQjbAfIOk8f5Y6T2wassN2wMCBB8CC6eUxLi14n2D6khHvkYvtPbXLHpXSHZWvEhqhvjAeSR5MmMrAth9WDSWUx7alO-ppsZpi8U7-g9Be5p6MRatc25voyTI2iTYbx02FQ",
  "refresh_token":"def50200d2fb757e4c01c333e96c827712dfd8f3e2c797db3e4e42734c8b4e7cba88a2dd8a9ce607358d634a51cadd7fa980d5acd692ab2c7a7da1d7a7f8246b22faf151dc11a758f9d8ea0b9aa3553f3cfd3751a927399ab964f219d086d36151d0f39c93aef4a846287e8467acea3dfde0bd2ac055ea7825dfb75aa5b8a084752de6d3976438631c3e539156a26bc10d0b7f057c092fce354bb10ff7ac2ab5fe6fd7af3ec7fa2599ec0f1e581837a6ca2441a80c01d997dac298e1f74573ac900dd4547d7a2a2807e9fb25438486c38f25be55d19cb8d72634d77c0a8dfaec80901c01745579d0f3822c717df21403440473c86277dc5590ce18acdb1222c1b95b516f3554c8b59255446bc15b457fdc17d5dcc0f06f7b2252581c810ca72b51618f820dbb2f414ea147add2658f8fbd5df20820843f98c22252dcffe127e6adb4a4cbe89ab0340f7ebe8d8177ef382569e2aa4a54d434adb797c5337bfdfffe27bd8d5cf4714054d4aef2372472ebb4"
}| token_type | the Bearer token value |
|---|---|
expires_in |
an integer representing the TTL of the access token |
access_token |
a JWT signed with the authorization server’s private key. It is required that you include this in the HTTP headers, each time you make a request to the API |
refresh_token |
an encrypted payload that can be used to refresh the access token when it expires. |
Created Tokens and Authorization Codes
All created OAuth2 clients, access tokens, refresh tokens and authorization codes are listed in the OAuth2 Clients and Tokens admin panel.
List OAuth2 Authorization Codes
To see the list of active codes, click on "List OAuth2 Authorization Codes". On the OAuth2 Authorization Codes page you will see a list of all created authorization codes, their associated client, user, expiration date. You can also revoke codes from this page.
List OAuth2 Tokens
To see the list of active tokens, click on "List OAuth2 Tokens". On the OAuth2 Tokens page you will see a list of all access tokens, their associated client, user, expiration date. You can also revoke tokens from this page.
