Environment OAuth2 Access Token Extension Generation Request object

The EnvironmentOAuth2AccessTokenExtensionGenerationRequest object overrides OAuth2 accessToken fields in multi-install integration packs (iPacks). It supports the OAuth2 authorization code (code) grant type only.

You provide details about the specific environment, extension group, connection, and OAuth client, and the API returns an OAuth2 authorization URL. Use this URL to log in to an authorization server, grant access, and then redirect back to Platform. After that, the remaining flow to record a new access token as an override for the extension group will be performed automatically. When a Connection that requires an OAuth2 access token is released within an iPack, the child account installing the iPack must generate a new token to execute the process that uses it. This object generates a new access token for the child account.

You can also use this object to query the status of a previously submitted access token generation request by providing only the requestId returned from the original request. An requestStatus value of ACCESS_TOKEN_RECEIVED indicates that a new access token has been generated and will be saved as an override.

Required Privileges

You need these privileges in the target environment:

Execute access

• API — Use the Boomi Platform API to access account data.
• Runtime Management (ATOM_MANAGEMENT) — Configure and administer integration runtimes.
• Environment Extensions Edit Access — View and edit Environment Extensions.

note

• Use the EnvironmentExtensions object to override the other OAuth2 credential fields. This object only generates a usable accessToken for process execution; fields such as clientId and clientSecret must still be available at runtime for actions like accessToken refresh.
• The field ID for accessToken is usually oauthOptions/OAuth2Config/credentials/@accessToken, but it can vary depending on the connector type. Use the EnvironmentMapExtensionsSummary query to find the field ID used for the specific connector being overridden.
• The URL returned in the XML response is escaped. If you test the result in a browser, replace & with &.
• Requires a process that uses a connector supporting OAuth2, with the accessToken field set up for extension. The clientId and clientSecret fields should also be set up for extension. This process is then packaged and released as a multi-install iPack.

Endpoint

All objects and operations share a single SOAP endpoint per account.

POST:

• US: https://api.boomi.com/api/soap/v1/<accountId>
• GB: https://api.platform.gb.boomi.com/api/soap/v1/<accountId>

Where accountId is the ID of the authenticating account for the request.

Structure

Request structure

<EnvironmentOAuth2AccessTokenExtensionGenerationRequest
   environmentId=""
   connectionId=""
   extensionGroupId=""
   oAuthFieldId=""
   clientId=""
   clientSecret=""
   requestId=""/>

Field	Type	Description
environmentId	string	The GUID of the environment where the extensions are being overridden.
connectionId	string	The component GUID of the connection being overridden.
extensionGroupId	string	The process ID for the instance of the multi-install integration pack. If not provided, the accessToken override applies to the environment instead of a specific iPack.
oAuthFieldId	string	The field ID of the accessToken for the given connector type. This is usually oauthOptions/OAuth2Config/credentials/@accessToken, but it can vary by connector type. Use the EnvironmentMapExtensionsSummary query to find the field ID for a specific connector.
clientId	string	The public ID of the OAuth2 application. If not provided, the platform tries to use the clientId saved in Environment Extensions, if available.
clientSecret	string	The secret key of the OAuth2 application.
requestId	string	A temporary ID generated by the platform that can optionally be used to track the access token generation request. Provide only this field to query the status of a previously submitted request.

Response structure

<EnvironmentOAuth2AccessTokenExtensionGenerationResponse requestId="" requestStatus="" success="">
   <authorizationCodeRequestUrl></authorizationCodeRequestUrl>
</EnvironmentOAuth2AccessTokenExtensionGenerationResponse>

Field	Type	Description
authorizationCodeRequestUrl	string	(Response-only field) The URL used to log in to the authorization server. After login, the authorization server redirects back to the platform with an authorization code.
requestId	string	(Response-only field) A temporary ID generated by the platform that can be used to track the access token generation request.
requestStatus	string	(Response-only field) The status of the accessToken generation: - GENERATED_URL — the API returned a URL to use for OAuth access token generation. - ACCESS_TOKEN_RECEIVED — the platform received the access token and started the process to record it as an override. - ERROR — the access token flow failed, likely due to an incorrect clientSecret. - UNKNOWN_REQUEST — the requestId provided is not active for the current user.
success	boolean	(Response-only field) Indicates whether the request was successful.

Supported operations

GET	QUERY	CREATE	UPDATE	EXECUTE	DELETE
Not supported	Not supported	Not supported	Not supported	Supported	Not supported

Using the EXECUTE operation

• Call the EXECUTE operation with environmentId, connectionId, extensionGroupId, oAuthFieldId, clientId, and clientSecret to generate an OAuth2 authorization URL. The response returns a requestId and a requestStatus of GENERATED_URL.

• Call the EXECUTE operation again with only requestId to check the status of a previously submitted request. The response returns the current requestStatus for that request (GENERATED_URL, ACCESS_TOKEN_RECEIVED, ERROR, or UNKNOWN_REQUEST).

• Refer Required Privileges for the privileges required to perform the EXECUTE operation.

SOAP implementation

EXECUTE operation

• Example 1: Generate an authorization URL

  Request:

  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.platform.boomi.com/">
     <soapenv:Header>
        <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
           <wsse:UsernameToken wsu:Id="UsernameToken" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
              <wsse:Username>user@boomi.com</wsse:Username>
              <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
           </wsse:UsernameToken>
        </wsse:Security>
     </soapenv:Header>
     <soapenv:Body>
        <api:execute>
           <api:objectType>EnvironmentOAuth2AccessTokenExtensionGenerationRequest</api:objectType>
           <api:objectId></api:objectId>
           <api:object xsi:type="api:EnvironmentOAuth2AccessTokenExtensionGenerationRequest"
              environmentId="1c950278-db6e-445e-9588-05bd916fe93f"
              connectionId="a6b9fdae-25ef-493f-b188-7c1eb8c3585b"
              extensionGroupId="ca492848-85bd-424e-85b9-c72690a47e9c"
              oAuthFieldId="oauthOptions/OAuth2Config/credentials/@accessToken"
              clientId="&lt;Client ID&gt;"
              clientSecret="&lt;Client Secret&gt;"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
        </api:execute>
     </soapenv:Body>
  </soapenv:Envelope>

  Response:

  <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
     <S:Body>
        <bns:executeResponse xmlns:bns="http://api.platform.boomi.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
           <bns:result xsi:type="bns:EnvironmentOAuth2AccessTokenExtensionGenerationResponse"
              requestId="0cd55b17-ae18-4222-b2ea-740d41b1d6ff" requestStatus="GENERATED_URL" success="true">
              <bns:authorizationCodeRequestUrl>[URL to Login to Authorization Server]</bns:authorizationCodeRequestUrl>
           </bns:result>
        </bns:executeResponse>
     </S:Body>
  </S:Envelope>

• Example 2: Check the status of a previously submitted request

  Request:

  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.platform.boomi.com/">
     <soapenv:Header>
        <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
           <wsse:UsernameToken wsu:Id="UsernameToken" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
              <wsse:Username>user@boomi.com</wsse:Username>
              <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password>
           </wsse:UsernameToken>
        </wsse:Security>
     </soapenv:Header>
     <soapenv:Body>
        <api:execute>
           <api:objectType>EnvironmentOAuth2AccessTokenExtensionGenerationRequest</api:objectType>
           <api:objectId></api:objectId>
           <api:object xsi:type="api:EnvironmentOAuth2AccessTokenExtensionGenerationRequest"
              requestId="117e59c2-346f-4cdd-a732-16bb9371f44f"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
        </api:execute>
     </soapenv:Body>
  </soapenv:Envelope>

  Response:

  <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
     <S:Body>
        <bns:executeResponse xmlns:bns="http://api.platform.boomi.com/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
           <bns:result xsi:type="bns:EnvironmentOAuth2AccessTokenExtensionGenerationResponse"
              requestId="117e59c2-346f-4cdd-a732-16bb9371f44f" requestStatus="ACCESS_TOKEN_RECEIVED" success="true"/>
        </bns:executeResponse>
     </S:Body>
  </S:Envelope>