Initialise OAuth 2.0 Connection
InitialiseOAuth2Connection returns a URL to redirect the user to an OAuth 2.0 Provider’s Authorize endpoint.
Only URLs constructed via this API can be used to connect to an OAuth 2.0 connector within
Versori, since a state parameter is generated and validated upon redirection to the
redirect_uri.
Additional query parameters can be added to the resultant URL via the additionalParams
property in the body. In addition to the standard parameters defined in the body, this API
adds the following parameters:
redirect_uri: The URI to redirect the user to after the OAuth 2.0 Provider has authenticated the user.state: A secure string generated by the API to authenticate requests to the redirect URI.prompt: See documentation on thepromptproperty of the request body.scope: See documentation on thescopesproperty of the request body.response_type: The response type to use. This is alwayscodefor OAuth 2.0.client_id: The client ID provided by the request body, this must match the client ID which is stored under the providedcredentialIdotherwise the handling of the redirect request will fail.
Full details on the standard parameters can be found in the OIDC Core specification: https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest
Authorizations
Bearer token authentication used by the Versori Platform. External consumers must provide an API key, however internal consumers must provide a JWT id_token issued by our IdP.
Path Parameters
ID is the unique identifier of the Connector.
Body
InitialiseOAuth2ConnectionRequest is the payload to initialise an OAuth 2.0 connection.
ID is the unique identifier of the credential which is being used to initialise the connection. This is used to load the client_secret when the authorisation code is exchanged for an access token.
OrganisationID is the unique identifier of the organisation which the credential is associated with. This is used to ensure that the credential is only used to initialise connections for the organisation which owns the credential.
AuthorizeURL is the URL which the user will be redirected to in order to authorize the application.
ClientID is the OAuth 2.0 client ID which is used to identify the application to the OAuth 2.0 provider.
Scopes is a list of OAuth 2.0 scopes which the application is requesting access to.
Unless disableOfflineAccess is set to true, the API will also include the standard
offline_access scope in addition to the ones provided here.
DisableOfflineAccess is a flag which can be set to true to disable the inclusion of the
standard offline_access scope in the list of scopes. This is defined separately to
scopes to make it clear that the API will always include the offline_access scope
by default, but can be disabled if the system does not implement the standards so that
the user can define their own custom scope as part of scopes.
Prompt controls the behaviour of the OAuth 2.0 provider when the user is redirected to the authorize URL. This is typically used to force the user to re-authenticate or to select a user account.
If set, should be one of "none", "login", "consent", "select_account". However the
specification dictates that arbitrary prompts may be provided in case of new values
added in the future. Some providers also allow multiple values to be provided, separated
by the '+' symbol, i.e. consent+select_account.
If not provided, this API defaults to "login", unless additionalParams contains the
approval_prompt parameter (thanks, Google refresh tokens), in which case this value
does not default to anything.
AdditionalParams is a URL-encoded query string which can be used to pass additional parameters to the OAuth 2.0 authorize endpoint. These cannot conflict with any of the other parameters defined by the request, an attempt to do so will result in an error.
These parameters are attached to returned URL as query parameters.
Response
InitialiseOAuth2ConnectionResponse contains the URL to redirect the user to in order to
initiate an OAuth 2.0 authorization_code grant flow.
The URL to redirect the user to.