Authorize external requests using OAuth 2.0

Level: intermediate

OAuth 2.0 is one of the supported authorization types in Creatio. This technology does not pass Creatio logins and passwords to third-party apps. Identity Service implements OAuth 2.0 in Creatio. Identity Service authorizes third-party 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 with Creatio. Learn more: official vendor website.

Before you authorize external requests to Creatio, set up OAuth 2.0. Instructions: OAuth 2.0 setup procedure (user documentation).

General procedure to authorize external requests using OAuth 2.0:

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

1. Retrieve an OAuth token

Creatio lets you authorize using OAuth 2.0 via the client credentials flow. Third-party apps and web services you integrate with Creatio receive OAuth token using client credentials for authentication. An OAuth token is an auto-generated token that lets you access Creatio API.

To retrieve an OAuth token:

1. Create a request.

   1. Add a request to the collection. Instructions: Adding requests to the collection.

   2. Fill out the request parameters.

      Parameter	Parameter description	Parameter value
      Request method		POST
      Request URL	Identity Service URL to retrieve an OAuth token.	https://[Identity Service URL]/connect/token

      Request

      POST https://[Identity Service URL]/connect/token

   3. Add the request body.

      1. Open the Body tab.

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

      3. Fill out the body parameters.

         Parameter (Key column)	Parameter description	Parameter value (Value column)
         client_id	The ClientId parameter value retrieved while configuring OAuth 2.0 authorization. Learn more: Generate OAuth 2.0 client credentials (user documentation).	D******5
         client_secret	The Client secret parameter value retrieved while configuring OAuth 2.0 authorization. Learn more: Generate OAuth 2.0 client credentials (user documentation).	4******C
         grant_type	The way a third-party app or web service uses to retrieve an OAuth token. Creatio supports client credentials flow.	client_credentials

   4. Save the request.

2. Execute the request.

As a result, you will retrieve the OAuth token.

Response

Status: 200 OK

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

You can now authorize external requests to Creatio using the OAuth token.

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

2. Access Creatio API using OAuth token

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

View an example that uses OAuth token and accesses Creatio API using OData 4 below. To do this:

1. Create a request.

   1. Add a request to the collection. Instructions: Adding requests to the collection.

   2. Fill out the request parameters based on your business goals. For example, access Creatio API using OData 4.

      Parameter	Parameter value
      Request method	GET
      Request URL	https://[Creatio URL]/0/odata/Account

      Request

      GET https://[Creatio URL]/0/odata/Account

   3. Save the request.

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 request.

   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 token and you will retrieve Creatio data using OData4.

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 token or change the token lifetime. Instructions: Change the OAuth 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

OAuth 2.0 setup procedure (user documentation)

Change the OAuth token lifetime

Postman basics

---

Resources

Creatio API documentation