Authorize external requests using client credentials grant

Level: intermediate

OAuth 2.0 is one of the supported authorization types in Creatio. This technology does not pass Creatio logins and passwords to external apps. Identity Service implements OAuth 2.0 in Creatio and authorizes external apps and web services you integrate with Creatio using OAuth 2.0. OAuth 2.0 also lets you restrict Creatio permissions for the integrated apps. For example, you can use OAuth 2.0 authorization to integrate webhook service, Power BI Connector, Clio, Creatio.ai add-in for Outlook with Creatio. Learn more: official vendor documentation (OAuth 2.0).

Before you authorize external requests to Creatio, set up client credentials grant. Instructions: Set up client credentials grant (user documentation).

This article covers setup procedure to authorize external requests using client credentials grant. Creatio also supports authorization code grant. Learn more: Authorize external requests using authorization code grant.

General procedure to authorize external requests using client credentials grant:

1. Retrieve an OAuth access token. Read more >>>
2. Access Creatio API using OAuth access token. Read more >>>

1. Retrieve an OAuth access token

Learn more: Access Token (OAuth 2.0 Authorization Framework). For example, use Postman to retrieve an OAuth access token. To do this:

1. Create a request.

   1. Add a request string. To do this, access the /connect/token endpoint.

      Request string

      POST IdentityServiceURL/connect/token

   2. Add a request body.

      1. Open the Body tab.

      2. Select x-www-form-urlencoded in the Body option parameter.

      3. Fill out the parameters of the request body.

         Parameter	Parameter description
         client_id	The ClientId parameter value retrieved while configuring client credentials grant. Learn more: Generate OAuth 2.0 client credentials (user documentation).
         client_secret	The Client secret parameter value retrieved while configuring client credentials grant. Learn more: Generate OAuth 2.0 client credentials (user documentation).
         grant_type	OAuth 2.0 authorization type. Requires the client_credentials value of the grantType parameter to retrieve an OAuth access token for client credentials grant.

   3. Save the changes.

2. Execute the request.

As a result, the OAuth access token will be retrieved.

Response

Status: 200 OK

{
    "access_token": "e******w",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": "ApplicationAccess_0******2"
}

You can now authorize external requests to Creatio using the OAuth access token via client credentials grant.

If needed, you can change the token lifetime for Creatio on-site. Instructions: Change the OAuth access token lifetime. To change the token lifetime for Creatio in the cloud, contact Creatio support.

2. Access Creatio API using OAuth access token

You can authorize external requests using OAuth access token via client credentials grant and access Creatio data and API using, for example, OData 4, DataService, or other web services. Learn more: Data services, Creatio API documentation, Web services.

For example, use Postman to access Creatio data and API using OAuth access token via OData 4. To do this:

1. Create a request.

   1. Add a request string. To do this, fill out the request parameters based on your business goals. For example, access Creatio data and API using OData 4.

      Request string

      GET CreatioURL/0/odata/Account

2. Connect the OAuth 2.0 authorization.

   1. Open the Authorization tab.

   2. Fill out the authorization parameters.

      Parameter	Parameter value
      Type	OAuth 2.0
      Token	e******w

   3. Save the changes.

   As a result, the auto-generated header will be added to the Headers tab. The header has the following parameters.

   Parameter	Parameter value
   Key	Authorization
   Value	Bearer e******w

   

3. Execute the request.

As a result, external requests will be authorized using OAuth access token and you will retrieve Creatio data using client credentials grant via OData 4.

Response

Status: 200 OK

{
    "@odata.context": "https://[Creatio URL]/0/odata/$metadata#Account",
    "value": [
        {
            "Id": "405947d0-2ffb-4ded-8675-0475f19f5a81",
            "Name": "Accom (sample)",
            "OwnerId": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
            "CreatedOn": "2019-08-19T13:46:11Z",
            "CreatedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
            "ModifiedOn": "2024-02-07T21:35:26.683Z",
            "ModifiedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
            "ProcessListeners": 0,
            "OwnershipId": "f7af2e24-f46b-1410-fb98-00155d043204",
            "PrimaryContactId": "c4ed336c-3e9b-40fe-8b82-5632476472b4",
            "ParentId": "00000000-0000-0000-0000-000000000000",
            "IndustryId": "fbbf0e52-f36b-1410-c493-00155d043205",
            "Code": "1",
            "TypeId": "03a75490-53e6-df11-971b-001d60e938c6",
            "Phone": "+1 617 440 2498",
            "AdditionalPhone": "",
            "Fax": "",
            "Web": "ac.com",
            "AddressTypeId": "780bf68c-4b6e-df11-b988-001d60e938c6",
            "Address": "31 Union Street",
            "CityId": "74144617-a288-4984-bcac-e78733277a61",
            "RegionId": "658acfe7-09ae-4747-b1b3-541e2dfa1b9e",
            "Zip": "02111",
            "CountryId": "e0be1264-f36b-1410-fa98-00155d043204",
            "AccountCategoryId": "38ea507c-55e6-df11-971b-001d60e938c6",
            "EmployeesNumberId": "ef7f0eb0-f36b-1410-849f-0026185bfcd3",
            "AnnualRevenueId": "bc30bdaa-55e6-df11-971b-001d60e938c6",
            "Notes": "",
            "AlternativeName": "Accom-Westhouse Company",
            "GPSN": "",
            "GPSE": "",
            "Completeness": 95,
            "AccountLogoId": "00000000-0000-0000-0000-000000000000",
            "AUM": "",
            "LeadConversionScore": 0,
            "PriceListId": "00000000-0000-0000-0000-000000000000",
            "Logo@odata.mediaEditLink": "Account(405947d0-2ffb-4ded-8675-0475f19f5a81)/Logo",
            "Logo@odata.mediaReadLink": "Account(405947d0-2ffb-4ded-8675-0475f19f5a81)/Logo",
            "Logo@odata.mediaContentType": "application/octet-stream"
        },
        {
            "Id": "e308b781-3c5b-4ecb-89ef-5c1ed4da488e",
            "Name": "Our company",
            "OwnerId": "00000000-0000-0000-0000-000000000000",
            "CreatedOn": "2011-01-30T15:22:43.771Z",
            "CreatedById": "22c5540c-d9b1-49ef-8eb7-72419b78e57c",
            "ModifiedOn": "2024-02-07T21:35:26.683Z",
            "ModifiedById": "410006e1-ca4e-4502-a9ec-e54d922d2c00",
            "ProcessListeners": 0,
            "OwnershipId": "00000000-0000-0000-0000-000000000000",
            "PrimaryContactId": "00000000-0000-0000-0000-000000000000",
            "ParentId": "00000000-0000-0000-0000-000000000000",
            "IndustryId": "00000000-0000-0000-0000-000000000000",
            "Code": "43",
            "TypeId": "57412fad-53e6-df11-971b-001d60e938c6",
            "Phone": "",
            "AdditionalPhone": "",
            "Fax": "",
            "Web": "",
            "AddressTypeId": "00000000-0000-0000-0000-000000000000",
            "Address": "",
            "CityId": "00000000-0000-0000-0000-000000000000",
            "RegionId": "00000000-0000-0000-0000-000000000000",
            "Zip": "",
            "CountryId": "00000000-0000-0000-0000-000000000000",
            "AccountCategoryId": "00000000-0000-0000-0000-000000000000",
            "EmployeesNumberId": "00000000-0000-0000-0000-000000000000",
            "AnnualRevenueId": "00000000-0000-0000-0000-000000000000",
            "Notes": "",
            "AlternativeName": "",
            "GPSN": "",
            "GPSE": "",
            "Completeness": 0,
            "AccountLogoId": "00000000-0000-0000-0000-000000000000",
            "AUM": "",
            "LeadConversionScore": 0,
            "PriceListId": "00000000-0000-0000-0000-000000000000",
            "Logo@odata.mediaEditLink": "Account(e308b781-3c5b-4ecb-89ef-5c1ed4da488e)/Logo",
            "Logo@odata.mediaReadLink": "Account(e308b781-3c5b-4ecb-89ef-5c1ed4da488e)/Logo",
            "Logo@odata.mediaContentType": "application/octet-stream"
        }
    ]
}

If the token lifetime expired, i. e., you got the 401 Unauthorized status code, retrieve a new OAuth access token or change the token lifetime. Instructions: Change the OAuth access token lifetime.

You can set up automated monitoring systems based on OAuth health monitoring. Instructions: OAuth health monitoring (user documentation). If needed, use Postman to check the health of OAuth functionality. The Postman request collection that tests requests is available in Creatio API documentation.

---

See also

Set up OAuth client credentials grant (user documentation)

Change the OAuth access token lifetime

Postman basics

---

Resources

Creatio API documentation