POST
/
o
/
{organisation_id}
/
connectors
/
{connector_id}
/
oauth2
/
initialise
Initialise OAuth 2.0 Connection
curl --request POST \
  --url https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/oauth2/initialise \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "credential": {
    "id": "<string>",
    "organisationId": "<string>"
  },
  "authorizeUrl": "<string>",
  "clientId": "<string>",
  "scopes": [
    "<string>"
  ],
  "disableOfflineAccess": true,
  "prompt": "<string>",
  "additionalParams": "<string>"
}'
{
  "url": "<string>"
}

Authorizations

​
Authorization
string
header
required

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

​
organisation_id
string<ulid>
required
​
connector_id
string<ulid>
required

ID is the unique identifier of the Connector.

Body

application/json

InitialiseOAuth2ConnectionRequest is the payload to initialise an OAuth 2.0 connection.

​
credential
object
required
​
authorizeUrl
string<uri>
required

AuthorizeURL is the URL which the user will be redirected to in order to authorize the application.

​
clientId
string
required

ClientID is the OAuth 2.0 client ID which is used to identify the application to the OAuth 2.0 provider.

​
scopes
string[]

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
boolean

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
string

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
string

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

OK

InitialiseOAuth2ConnectionResponse contains the URL to redirect the user to in order to initiate an OAuth 2.0 authorization_code grant flow.

​
url
string
required

The URL to redirect the user to.