Authorization – InterAction+™ Integration Answer Center

The InterAction+™ Cloud API uses OAuth 2.0 as the authorization framework, enabling Third-Party Client applications to securely access user data for a tenant, without requiring users to share their passwords. Authorization is managed by InterAction+™ Authorization Server, which issues secure access and refresh tokens that grant controlled access to the InterAction+™ Cloud API.

OAuth 2.0 Authorization Flow

Our implementation supports the OAuth 2.0 Authorization Code Grant flow, ensuring secure authentication and authorization for system-to-system interactions. This flow ensures that only authenticated and authorized Third-Party Clients can securely interact with the InterAction+™ Cloud API while maintaining strict control over access permissions.

Key Participants

InterAction+™ Tenant Admin: Initiates the authorization process to grant a Third-Party Client access to the InterAction+™ Cloud API. An admin must provide consent for access to InterAction+™ data, ensuring that API access is only granted to authorized Third-Party Client. Additionally, the admin must designate a single user for API transactions. It is recommended to create and pick a dedicated system user without any personal data for this purpose.
Third-Party Client: Requests an access token from the InterAction+™ Authorization Server to interact with the InterAction+™ Cloud API on behalf of the tenant. Access is granted only for requested scopes within the confines of the Third-Party Client configuration.
Tenant’s Identity Provider (IdP): Authenticates the InterAction+™ Tenant Admin before issuing an authorization code.
InterAction+™ Authorization Server: Issues access and refresh tokens upon successful authorization.

Authorization Steps

The outlined steps break down each individual request made to the InterAction+™ Authorization Server during the OAuth 2.0 Authorization Code Grant flow. While these details provide a deeper understanding of the process, many tools (e.g., Postman) and frameworks handle these requests automatically. In such cases, users only need to configure the Authorization URL, Access Token URL, and Refresh Token URL to enable authentication and token exchange.

InterAction+™ Tenant Admin Authorizes Third-Party Client: To grant a Third-Party Client access to the InterAction+™ Cloud API, the InterAction+™ Tenant Admin must initiate the setup process within the Third-Party Client's interface. Upon initiation, the Third-Party Client sends a request to the authorize endpoint, prompting the InterAction+™ Tenant Admin to complete the following steps before obtaining an authorization code:

Authenticate with Identity Provider (IdP): The InterAction+™ Tenant Admin must log in using their organization's IdP credentials to verify their identity. This step ensures secure authentication before granting access.
Grant Consent for Third-Party Client Access: After authentication, the InterAction+™ Tenant Admin will review and approve the Third-Party Client’s request to access InterAction+™ tenant data.
Designate an API User: The InterAction+™ Tenant Admin must assign a designated user responsible for managing InterAction+™ Cloud API transactions within the tenant. The InterAction+™ Tenant Admin must assign a designated user responsible for managing InterAction+™ Cloud API transactions within the tenant.

Endpoint:

GET {InterAction+™ Tenant Authority URL}/connect/authorize

Parameter	Description
response_type=code	Requests an authorization code.
client_id	The Third-Party Client’s unique identifier.
redirect_uri	The OAuth Return URL where the authorization code will be sent (registered during client onboarding).
scope	The requested permissions (e.g., openid offline_access public.contact.read).
state	A random value to prevent CSRF attacks.

Scopes: Scopes define the level of access granted to the Third-Party Client. The InterAction+™ Cloud API access token issued by the InterAction+™ Authorization Server encompasses scopes requested by the Third-Party Client within the confines of its configuration.

Scope	Description
openid	Enables OpenID Connect support, allowing identity verification.
offline_access	Allows requesting a refresh token, so that the Third-Party Client can obtain new access token without requiring user interaction.
public.activity.read	Read activities
public.activity.modify	Modify activities
public.contact.read	Read contacts and related information
public.contact.modify	Modify contacts and related information
public.list.read	Read lists
public.list.modify	Modify lists and related information

Example Authorization Request:

{InterAction+™ Tenant Authority URL}/connect/authorize?response_type=code&client_id=third-party-client-id&redirect_uri=https://thirdpartyapp.com/oauth/callback&scope=openid offline_access public.contact.read&state=xyz123

Exchange Authorization Code for Access and Refresh Tokens: Once the authorization code is obtained, the Third-Party Client must exchange it for an Access Token and Refresh Token by making a request to the Token Endpoint.

Token Endpoint:

POST {InterAction+™ Tenant Authority URL}/connect/token

Parameter	Description
grant_type=authorization_code	Specifies the Authorization Code grant type.
code	The authorization code received from the previous step.
redirect_uri	The OAuth Return URL where the tokens will be sent (registered during client onboarding).
client_id	The Third-Party Client Identifier.
client_secret	The Third-Party Client Secret.

Example Token Exchange Request:

POST {InterAction+™ Tenant Authority URL}/connect/token

Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=third-party-client-
id&client_secret=third-party-client-
secret&code=AUTHORIZATION_CODE_FROM_STEP_1&redirect_uri=https://third-
party-app.com/oauth/callback

Example Token Response:

{
    "id_token": "eyJhbGciOiJIUzI1NiIsInR...",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR...",
    "expires_in": 3600,
    "refresh_token": "def5020072b36c9b...",
    "token_type": "Bearer",
    "scope": "openid public.activity.read …”
}

Token	Description
id_token	JWT that contains user authentication information.
access_token	JWT token used to access the InterAction+™ Cloud API.
expires_in	Expiration time of the Access Token (in seconds).
refresh_token	Refresh Token used to request a new Access Token without user interaction.
token_type	Always Bearer, used in Authorization headers.
scope	The level of access granted to the Third-Party Client.

Making API Requests with the Access Token: Once the access token is obtained, the Third-Party Client includes it in the Authorization header of API requests. This mechanism ensures that only authenticated users with a valid JWT access token can access the InterAction+™ Cloud API.
- Example API Request:
```
POST {InterAction+™ Cloud API URL}
```
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR...
```
```
Body: GraphQL request
```

Refreshing Access Token: Since access tokens have a shorter lifespan, the refresh token allows the Third-Party Client to obtain a new access token without requiring user interaction.

Token Endpoint:

POST {InterAction+™ Tenant Authority URL}/connect/token

Parameter	Description
grant_type=refresh_token	Specifies the grant type to retrieve refresh token.
refresh_token	The Refresh Token received from the previous step.
client_id	The Third-Party Client Identifier.
client_secret	The Third-Party Client Secret.

Example Request:

POST {InterAction+™ Tenant Authority URL}/connect/token

Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id=third-party-client-id&client_secret=third-party-client-secret&refresh_token=REFRESH_TOKEN

Example Refresh Token Response:

{ 
    "id_token": "new_id_token_here",
    "access_token": "new_access_token_here",
    "expires_in": 3600,
    "refresh_token": "new_refresh_token_here",
    "token_type": "Bearer"
     "scope": "openid public.activity.read …”
}

Token	Description
id_token	JWT that contains user authentication information.
access_token	JWT token used to access the InterAction+™ Cloud API.
expires_in	Expiration time of the Access Token (in seconds).
refresh_token	Refresh Token used to request a new Access Token without user interaction.
token_type	Always Bearer, used in Authorization headers.
scope	The level of access granted to the Third-Party Client.

Token Lifecycle

Access Token Expiration: The Access Token is valid for one hour.
Refresh Token Expiration: The Refresh Token is valid for 30 days. If the Refresh Token expires, the InterAction+™ Tenant Admin must reinitiate the authorization process to obtain new tokens.
Token Revocation: The InterAction+™ Tenant Admin can revoke access tokens for a Third-Party Client at any time, immediately terminating API access from tenant administration in CIM. Refer to the Client Insights Answer Center for Hybrid or SaaS users to learn more.

Refresh Token Usage

Our configuration implements one-time-use refresh tokens to support secure token management.

When a Third-Party Client uses a refresh token to obtain a new access token, a new pair of access and refresh tokens is issued.
The previously used refresh token is revoked immediately and can no longer be used.

If a Third-Party Client submits a refresh token that has already been used or one that has been superseded by a newer token, the request will fail with an error because the token is no longer valid or present in our token store.

Best Practices

After each successful refresh, replace your stored refresh token with the new one and use only the most recent token for future refresh requests.
Do not attempt to reuse or fall back to previous refresh tokens.
Avoid sending multiple refresh requests in parallel, as the first request will rotate the token and subsequent ones using the old token will fail.

Search

InterAction+™ Integration Answer Center