> ## Documentation Index > Fetch the complete documentation index at: https://docs.versori.com/llms.txt > Use this file to discover all available pages before exploring further. # 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 the `prompt` property of the request body. - `scope`: See documentation on the `scopes` property of the request body. - `response_type`: The response type to use. This is always `code` for OAuth 2.0. - `client_id`: The client ID provided by the request body, this must match the client ID which is stored under the provided `credentialId` otherwise 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 ## OpenAPI ````yaml /openapi/platform-api.yaml post /o/{organisation_id}/systems/{system_id}/oauth2/initialise openapi: 3.1.0 info: title: Versori Platform API version: 0.0.1 license: name: UNLICENSED servers: - description: Production url: https://platform.versori.com/api/v2 - description: Staging url: https://platform-staging.versori.com/api/v2 - description: Development url: http://localhost:8901 security: - bearerToken: [] - cookie: [] paths: /o/{organisation_id}/systems/{system_id}/oauth2/initialise: parameters: - $ref: '#/components/parameters/organisation_id' - $ref: '#/components/parameters/system_id' post: tags: - connections summary: Initialise OAuth 2.0 Connection description: > 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 the `prompt` property of the request body. - `scope`: See documentation on the `scopes` property of the request body. - `response_type`: The response type to use. This is always `code` for OAuth 2.0. - `client_id`: The client ID provided by the request body, this must match the client ID which is stored under the provided `credentialId` otherwise 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 operationId: InitialiseOAuth2Connection requestBody: content: application/json: schema: $ref: '#/components/schemas/InitialiseOAuth2ConnectionRequest' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/InitialiseOAuth2ConnectionResponse' default: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: organisation_id: name: organisation_id in: path required: true schema: type: string format: ulid x-go-type: ulid.ULID x-go-name: OrganisationID x-go-type-import: path: versori.dev/vergo/ulid system_id: name: system_id in: path required: true schema: type: string format: ulid x-go-type: ulid.ULID x-go-name: SystemID x-go-type-import: path: versori.dev/vergo/ulid schemas: InitialiseOAuth2ConnectionRequest: description: > InitialiseOAuth2ConnectionRequest is the payload to initialise an OAuth 2.0 connection. type: object properties: credential: type: object properties: id: description: > 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. type: string format: ulid x-go-name: ID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid organisationId: description: > 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. type: string format: ulid x-go-name: OrganisationID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid required: - id - organisationId authorizeUrl: description: > AuthorizeURL is the URL which the user will be redirected to in order to authorize the application. type: string format: uri x-go-name: AuthorizeURL clientId: description: > ClientID is the OAuth 2.0 client ID which is used to identify the application to the OAuth 2.0 provider. type: string x-go-name: ClientID scopes: description: > 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. type: array items: type: string x-go-type-skip-optional-pointer: true disableOfflineAccess: description: > 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`. type: boolean x-go-type-skip-optional-pointer: true prompt: description: > 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. type: string additionalParams: description: > 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. type: string examples: two query parameters: bar=baz&foo=cat%20bob x-go-type-skip-optional-pointer: true required: - credential - authorizeUrl - clientId InitialiseOAuth2ConnectionResponse: description: > InitialiseOAuth2ConnectionResponse contains the URL to redirect the user to in order to initiate an OAuth 2.0 `authorization_code` grant flow. type: object properties: url: description: The URL to redirect the user to. type: string x-go-name: URL required: - url Error: type: object properties: code: type: string description: Code is a machine-readable error code. message: type: string description: Message is a human-readable error message. fields: type: array items: $ref: '#/components/schemas/ErrorField' x-go-type-skip-optional-pointer: true details: type: string x-go-type-skip-optional-pointer: true required: - code - message ErrorField: description: ErrorField denotes a field which has an error. type: object properties: field: type: string description: > Field is the name of the field which has an error, this may be a path to a nested field, including array elements. The format of this field is of the form: "field1.field2[0].field3" message: type: string description: Message is the error message for this specific field. required: - field - message securitySchemes: bearerToken: description: > 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. type: http scheme: bearer cookie: description: Cookie authentication used by the Versori Platform. type: apiKey in: cookie name: cookie ````