Version: 8.3

Manage OAuth integrations using API

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

Creatio lets you set up OAuth 2.0 in multiple ways:

using OAuth 2.0 integrated applications page. Instructions: Set up client credentials grant, Set up authorization code grant (user documentation).
using API. Creatio includes the OAuthConfigService web service to set up OAuth 2.0 using API.

Add OAuth integration

Creatio supports the following OAuth 2.0 authorization types:

Client credentials grant (server-to-server)
Authorization code grant (on behalf of a user)

You can add both of them using API.

To add OAuth integration:

Create a request string. To do this, access the /OAuthConfigService/AddClient endpoint.
Request string
```
POST CreatioURL/0/rest/OAuthConfigService/AddClient
```

Create a request body. To do this, fill out the parameters of the addClientRequest configuration object in request body.

Parameter

Parameter description

name*

Name of the integration that Creatio and logs will use. Find the parameter value in the Name column on the OAuth integrated applications page.

redirectUrl

Redirect URIs to receive authorization codes when authorizing integrated app. Find the parameter value in the Authorized redirect URIs expanded list on the integration page.

API lets you specify one redirect URI in one request while adding OAuth integration. You can extend the list of redirect URIs. If you omit the parameter value, no URI is authorized to receive authorization code, and the request will be rejected. Requires the authorization_code value of the grantType parameter.

applicationUrl*

The URL of the external app or web service. Find the parameter value in the Application URL column on the OAuth integrated applications page.

systemUserId

ID of technical user created for the integration. Find the parameter value in the Id column on the Technical users page. Requires the client_credentials value of the grantType parameter.

grant_type*

OAuth 2.0 authorization type. Find the parameter value in the Grant type column on the OAuth integrated applications page.

Available values

client_credentials	Client credentials grant (server-to-server).
authorization_code	Authorization code grant (on behalf of a user).

View the examples that create a request body to add different types of OAuth 2.0 below.

Request body (client credentials grant)
Request body (authorization code grant)

{
    "addClientRequest": {
        "name": "PowerBI",
        "applicationUrl": "test.com",
        "systemUserId": "7F3B869F-34F3-4F20-AB4D-7480A5FDF648",
        "grantType": "client_credentials"
    }
}

{
    "addClientRequest": {
        "name": "PowerBI",
        "redirectUrl": "test.com/redirect",
        "applicationUrl": "test.com",
        "grantType": "authorization_code"
    }
}

Execute the request.

As a result, the new OAuth integration of specified type will be added to the OAuth integrated applications page.

Manage redirect URIs (for authorization code grant)

Add redirect URI

Create a request string. To do this, access the /OAuthConfigService/AddRedirectUrls endpoint.
Request string
```
POST CreatioURL/0/rest/OAuthConfigService/AddRedirectUrls
```

Create a request body. To do this, fill out the parameters of the redirectUrlsRequest configuration object in request body.

Parameter	Parameter description
clientId*	ID of the integrated app. Find the parameter value in the Client Id field on the integration page.
redirectUrls*	Redirect URIs to receive authorization codes when authorizing integrated app. Specify one or more redirect URIs. If no URI is authorized to receive authorization code, the request will be rejected. Find the parameter value in the Authorized redirect URIs expanded list on the integration page.

View the example that adds a list of redirect URIs to authorization code grant below.

Request body
{
    "redirectUrlsRequest": {
        "clientId": "07D1936A2EA29D020586B5D04C676984",
        "redirectUrls": [
            "http://test1.com",
            "http://test2.com"
        ]
    }
}

Execute the request.

As a result, one or more redirect URIs will be added to the Authorized redirect URIs expanded list on the integration page.

Update a dedicated redirect URI

Creatio API lets you update one redirect URI in one request. To do this:

Create a request string. To do this, access the /OAuthConfigService/UpdateRedirectUrl endpoint.
Request string
```
POST CreatioURL/0/rest/OAuthConfigService/UpdateRedirectUrl
```

Create a request body. To do this, fill out the parameters of the updateRedirectUrlRequest configuration object in request body.

Parameter	Parameter description
redirectUrlId*	ID of the redirect URI to update. Find the parameter value in the Id column in the Authorized redirect URIs expanded list on the integration page.
redirectUrl*	New value of redirect URI.

View the example that updates a redirect URI to authorization code grant below.

Request body
{
    "updateRedirectUrlRequest": {
        "redirectUrlId": "97525A0F-3019-4567-A0EA-818D913892E1",
        "redirectUrl": "http://test4.com"
    }
}

Execute the request.

As a result:

a dedicated redirect URI will be updated
the new value will be displayed in the Authorized redirect URIs expanded list on the integration page

Delete a dedicated redirect URI

Creatio API lets you delete one redirect URI in one request. To do this:

Create a request string. To do this, access the /OAuthConfigService/DeleteRedirectUrl endpoint.
Request string
```
POST CreatioURL/0/rest/OAuthConfigService/DeleteRedirectUrl
```
Create a request body. To do this, fill out the parameters of the deleteRedirectUrlRequest configuration object in request body.

Parameter
Parameter description
redirectUrlId*
ID of the redirect URI to delete. Find the parameter value in the Id column in the Authorized redirect URIs expanded list on the integration page.

View the example that deletes a redirect URI from authorization code grant below.
Request body
```
{
    "deleteRedirectUrlRequest": {
        "redirectUrlId": "97525A0F-3019-4567-A0EA-818D913892E1"
    }
}
```
Execute the request.

Parameter	Parameter description
redirectUrlId*	ID of the redirect URI to delete. Find the parameter value in the Id column in the Authorized redirect URIs expanded list on the integration page.

As a result, a dedicated redirect URI will be deleted from the Authorized redirect URIs expanded list on the integration page.

Resources

Official vendor documentation (OAuth 2.0)

Add OAuth integration​

Manage redirect URIs (for authorization code grant)​

Add redirect URI​

Update a dedicated redirect URI​

Delete a dedicated redirect URI​

See also​

Resources​