Skip to main content
Version: 8.1

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