> ## 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. # Retrieve an Embedded Integration > GetEmbeddedIntegration returns the Integration for the given ID to be displayed to the user in the embedded UI. ## OpenAPI ````yaml get /embed/{hub_id}/users/{user_id}/integrations/{integration_id} openapi: 3.1.0 info: title: Versori Embedded API version: 0.0.1 license: name: UNLICENSED identifier: UNLICENSED description: V1 API for managing embedded integrations servers: - description: Production url: https://platform.versori.com/api/embedded/v1 - description: Staging url: https://platform-staging.versori.com/api/embedded/v1/ - description: Development url: http://localhost:8950/embedded/v1 security: [] tags: - name: Hubs - name: End Users - name: Connectors - name: Integrations - name: Connections - name: Embedded - name: Miscellaneous - name: Internal paths: /embed/{hub_id}/users/{user_id}/integrations/{integration_id}: parameters: - $ref: '#/components/parameters/hub_id' - $ref: '#/components/parameters/user_id' - $ref: '#/components/parameters/integration_id' - $ref: '#/components/parameters/identifier_type' get: tags: - Embedded summary: Retrieve an Embedded Integration description: > GetEmbeddedIntegration returns the Integration for the given ID to be displayed to the user in the embedded UI. operationId: GetEmbeddedIntegration responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/EmbeddedIntegration' default: description: Error content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: hub_id: name: hub_id in: path required: true schema: $ref: '#/components/schemas/ULID' user_id: description: > UserID references an End User in the Hub. Most APIs support setting this value to either the internal Versori identifier or their external ID as determined by the organisation. The `identifier_type` query parameter is used to indicate which type of ID is being used. name: user_id in: path required: true schema: type: string integration_id: name: integration_id in: path required: true schema: $ref: '#/components/schemas/ULID' identifier_type: name: identifier_type in: query description: > IdentifierType indicates whether the `user_id` path parameter is a internal identifier created by Versori, or an external identifier. If the value is `external`, some endpoints also require the `hub` query parameter to identify the correct Hub. required: false schema: type: string enum: - internal - external default: external schemas: EmbeddedIntegration: description: > EmbeddedIntegration represents an integration that is available to an end user and contains all the necessary information for the UI to determine how the user should activate the integration. type: object properties: id: $ref: '#/components/schemas/ULID' description: ID is the unique identifier for the Integration name: description: > Name is a short name for the integration, this is typically the name of the Connector being integrated to. type: string imageUrl: description: > ImageURL is a URL to an image/icon that represents the integration. This image is used within the integration tile displayed in the embedded UI. type: string format: uri x-go-name: ImageURL variablesSchema: description: > VariablesSchema is the JSON schema for the variables defined for this integration. type: object x-go-type-skip-optional-pointer: true x-go-type: json.RawMessage description: description: > Description can be used to provide a longer description of the integration. This can be shown to end users in the embedded integration hub UI. type: string isDeployed: description: > IsDeployed indicates whether the integration is deployed and available to end users. If not deployed, the integration cannot be activated. type: boolean isActivated: description: > IsActivated indicates whether the integration is activated for the end user. If the integration is not activated, the user can activate it from the embedded integration hub. type: boolean connectionTemplates: description: > ConnectionTemplates is a list of connections that the end user can authenticate to when activating the integration. type: array items: $ref: '#/components/schemas/HubConnectionTemplate' required: - id - name - imageUrl - description - isDeployed - isActivated - connectionTemplates 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 ULID: type: string format: ulid x-go-type: ulid.ULID x-go-type-skip-optional-pointer: true x-go-type-import: path: versori.dev/vergo/ulid HubConnectionTemplate: description: > A Hub Connection Template is a lightweight wrapper around a Connector from Connect API, but includes additional information to make embedding the integration simpler. Versori-users do not need to establish connections in an integration. These are connected to by end-users when they activate the integration from the embedded integration hub. type: object properties: id: description: ID is the unique identifier of the Hub Connection Template. type: string format: ulid x-go-type: ulid.ULID x-go-type-skip-optional-pointer: true x-go-type-import: path: versori.dev/vergo/ulid x-go-name: ID connectorId: description: ConnectorID is the unique identifier of the Connector. type: string format: ulid x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid x-go-type-skip-optional-pointer: true x-go-name: ConnectorID imageUrl: description: > ImageURL is a URL to an image/icon that represents the connector. This image is used within the integration tile displayed in the embedded UI. type: string format: uri x-go-name: ImageURL name: description: > name denotes the name of the Connector that the template is wrapping. type: string isUsed: type: boolean description: IsUsed indicates that this connection template is in use by the hub. isPrimary: type: boolean description: IsPrimary indicates that this is the primary connections on the hub. authSchemeConfig: $ref: '#/components/schemas/AuthSchemeConfig' required: - id - connectorId - name - imageUrl - connectionTemplates - variables - authSchemeConfig - isUsed - isPrimary 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 AuthSchemeConfig: description: > AuthSchemeConfig defines how a Connector implements the AuthScheme in order to fulfil its authentication requirements. This is purely the configuration and not the actual credential which is used to authenticate. The credential uses this configuration to determine how to authenticate. discriminator: propertyName: schemeType mapping: none: $ref: '#/components/schemas/AuthSchemeConfigNone' api-key: $ref: '#/components/schemas/AuthSchemeConfigAPIKey' basic-auth: $ref: '#/components/schemas/AuthSchemeConfigBasicAuth' oauth2: $ref: '#/components/schemas/AuthSchemeConfigOAuth2' hmac: $ref: '#/components/schemas/AuthSchemeConfigHMAC' certificate: $ref: '#/components/schemas/AuthSchemeConfigCertificate' oneOf: - $ref: '#/components/schemas/AuthSchemeConfigNone' - $ref: '#/components/schemas/AuthSchemeConfigAPIKey' - $ref: '#/components/schemas/AuthSchemeConfigBasicAuth' - $ref: '#/components/schemas/AuthSchemeConfigOAuth2' - $ref: '#/components/schemas/AuthSchemeConfigHMAC' - $ref: '#/components/schemas/AuthSchemeConfigCertificate' AuthSchemeConfigNone: description: > AuthSchemeConfigNone is a placeholder object with the schemeType set to `none`. There is no other configuration required. type: object allOf: - $ref: '#/components/schemas/AuthSchemeConfigBase' - type: object properties: schemeType: type: string const: none required: - schemeType AuthSchemeConfigAPIKey: description: > AuthSchemeConfigAPIKey defines how a Connector uses an API key credential to authenticate with the system. type: object allOf: - $ref: '#/components/schemas/AuthSchemeConfigBase' - type: object properties: schemeType: type: string const: api-key name: type: string description: >- Name is the query parameter/header/cookie name which will be used to send the API key. in: $ref: '#/components/schemas/AuthSchemeConfigAPIKeyIn' required: - schemeType - name - in AuthSchemeConfigBasicAuth: description: > AuthSchemeConfigBasicAuth is a placeholder object with the schemeType set to `basic-auth`. There is no other configuration required. type: object allOf: - $ref: '#/components/schemas/AuthSchemeConfigBase' - type: object properties: schemeType: type: string const: basic-auth required: - schemeType AuthSchemeConfigOAuth2: description: > AuthSchemeConfigOAuth2 defines how a Connector uses an OAuth2 credential to authenticate with the system. This is to be used for all OAuth 2.0 flows which require a client ID and client secret as part of the Connector's configuration. Connectors which use the `client_credentials` grant type, where the user provides the Client ID and Client Secret at the point where they connect, should use the `AuthSchemeConfigOAuth2ClientCredentials` type instead. type: object allOf: - $ref: '#/components/schemas/AuthSchemeConfigBase' - type: object properties: schemeType: type: string const: oauth2 authorizeUrl: type: string format: uri description: > AuthorizeURL is the URL which the user will be redirected to in order to authorize the application. x-go-name: AuthorizeURL tokenUrl: type: string format: uri description: > TokenURL is the URL which the application will use to issue an access token. x-go-name: TokenURL scopes: description: > Scopes is the list of all OAuth2 scopes which the application supports. The user will be allowed to choose which scopes to request when configuring the Connection. type: array items: $ref: '#/components/schemas/OAuth2Scope' defaultScopes: description: > DefaultScopes is the list of scopes which will be requested by default when the user connects the Connector. This is useful for Connectors which require a specific set of scopes to function correctly. type: array items: type: string additionalAuthorizeParams: description: > AdditionalAuthorizeParams is a URL-encoded query string which should be attached to the AuthorizeURL when the user is redirected to the OAuth 2.0 authorization endpoint. This value is only used by the UI to drive the default values when connecting, the API to `InitialiseOAuth2Connection` can be provided a different value if required. type: string x-go-type-skip-optional-pointer: true additionalTokenParams: description: > AdditionalTokenParams is a URL-encoded string following the `application/x-www-form-urlencoded` mime-type, which can be used to pass additional parameters to the OAuth 2.0 token endpoint within the request body. type: string x-go-type-skip-optional-pointer: true mtlsEnabled: type: boolean description: > MTLSEnabled is a flag which determines whether the Connector should use Mutual TLS (mTLS) to authenticate with the OAuth 2.0 token endpoint. This is useful for Connectors which require a higher level of security. x-go-name: MTLSEnabled x-go-type-skip-optional-pointer: true mtlsCredentialId: type: string description: > MTLSCredentialID is the unique identifier of the Credential which contains the client certificate and private key to be used as part of the mTLS connection. This may be unset when creating a connection, in which case if `mtlsEnabled` is true, then the API will find an associated AuthSchemeConfigCertificate and link them automatically. x-go-name: MTLSCredentialID grant: $ref: '#/components/schemas/AuthSchemeConfigOAuth2Grant' required: - schemeType - authorizeUrl - tokenUrl - scopes - defaultScopes - grant AuthSchemeConfigHMAC: description: > AuthSchemeConfigHMAC defines how a Connector uses an HMAC credential to authenticate with the system. This may be used on outbound requests to sign the request body, however it is more commonly used on inbound requests (i.e. from Webhook Triggers) to verify the sender of the request is allowed to invoke the Trigger. type: object allOf: - $ref: '#/components/schemas/AuthSchemeConfigBase' - type: object properties: schemeType: type: string const: hmac name: type: string description: >- Name is the query parameter/header/cookie name which will be used to send the signature. in: $ref: '#/components/schemas/AuthSchemeConfigHMACIn' algorithm: description: >- AuthSchemeConfigHMACAlgorithm defines the hashing algorithm to use when generating the HMAC signature. type: string enum: - sha1 - sha256 - sha512 digestInputs: description: > AuthSchemeConfigHMACInputs defines what parts of a HTTP request are consumed to generate the HMAC signature. Some systems only generate the signature from the request body, others may include the URL. The order of this array defines the order in which the input is fed into the hashing function. type: array items: type: string enum: - body - url required: - schemeType - name - in - algorithm - digestInputs AuthSchemeConfigCertificate: description: > AuthSchemeConfigCertificate is a placeholder object with the schemeType set to `certificate`. There is no other config required type: object allOf: - $ref: '#/components/schemas/AuthSchemeConfigBase' - type: object properties: schemeType: type: string const: certificate required: - schemeType AuthSchemeConfigBase: type: object properties: id: type: string format: ulid description: > ID is the unique identifier of the AuthSchemeConfig, this is generated by the client and only requires to be unique amongst the elements of the array in which is it contained. x-go-name: ID description: description: > Description enables users to distinguish multiple configurations which use the same schemeType. type: string validationMessages: description: > ValidationMessages is a list of messages which are generated when the AuthSchemeConfig is validated. This is typically used to provide feedback to the user when they are creating or updating the AuthSchemeConfig. This field will be ignored if sent to the API. type: array items: $ref: '#/components/schemas/Message' x-go-type-skip-optional-pointer: true required: - id - description AuthSchemeConfigAPIKeyIn: description: > AuthSchemeConfigAPIKeyIn defines the location of the API key in the request. type: string enum: - query - header - cookie OAuth2Scope: description: > OAuth2Scope represents a single scope which can be requested by an OAuth2 application. type: object properties: name: type: string description: > Name is the name of the scope as determined by the application to which this Connector is connecting to. description: type: string description: > Description describes the scope in human-friendly terminology. This text may be displayed to users via a help tooltip or similar. x-go-type-skip-optional-pointer: true required: - name AuthSchemeConfigOAuth2Grant: type: object discriminator: propertyName: grantType mapping: authorization_code: $ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantAuthorizationCode' client_credentials: $ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantClientCredentials' password: $ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantPassword' oneOf: - $ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantAuthorizationCode' - $ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantClientCredentials' - $ref: '#/components/schemas/AuthSchemeConfigOAuth2GrantPassword' AuthSchemeConfigHMACIn: description: >- AuthSchemeConfigHMACIn defines where the signature should be set on requests. type: string enum: - query - header - cookie Message: description: > Message is a message to be displayed to the user to indicate some information about the preceding request. type: object properties: text: description: Text contains the text of the message. type: string severity: $ref: '#/components/schemas/MessageSeverity' detail: description: > Details contains additional information about the message. This is intended to be used to provide more information about the message, such as a list of validation errors. type: array items: type: string x-go-type-skip-optional-pointer: true required: - text - severity AuthSchemeConfigOAuth2GrantAuthorizationCode: description: > AuthSchemeConfigOAuth2GrantAuthorizationCode contains grant-specific configuration for the `authorization_code` grant type. How the API manages changes to this configuration is as follows: - CredentialID and OrganisationID are not set, a new credential is created containing the sensitive information and the non-sensitive information is updated in the database. - Otherwise, both the credential and the database are updated using JSON Merge Patch, with undefined properties not being updated. - Any other permutation will result in a 400 Bad Request. type: object properties: grantType: type: string const: authorization_code credentialId: description: > CredentialID is the unique identifier of the Credential which contains the client ID and client secret to be used as part of the `password` flow. type: string format: ulid x-go-name: CredentialID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid x-go-type-skip-optional-pointer: true organisationId: description: > OrganisationID is the unique identifier of the Organisation that owns the Credential. This can be different to the Connector's OrganisationID since some may be imported from Versori's public library. type: string format: ulid x-go-name: OrganisationID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid x-go-type-skip-optional-pointer: true clientId: description: > ClientID is the OAuth 2.0 client's identifier. This is not a sensitive value and may be presented to the user in plaintext. type: string x-go-name: ClientID clientSecret: description: > ClientSecret is the OAuth 2.0 client's secret. This is a sensitive value and will not be displayed to the user. type: string required: - grantType AuthSchemeConfigOAuth2GrantClientCredentials: type: object properties: grantType: type: string const: client_credentials required: - grantType AuthSchemeConfigOAuth2GrantPassword: description: > AuthSchemeConfigOAuth2GrantPassword contains grant-specific configuration for the `password` grant type. How the API manages changes to this configuration is as follows: - CredentialID and OrganisationID are not set, a new credential is created containing the sensitive information and the non-sensitive information is created/updated in the database. - Otherwise, both the credential and the database are updated using JSON Merge Patch. - Any other permutation will result in a 400 Bad Request. type: object properties: grantType: type: string const: password credentialId: description: > CredentialID is the unique identifier of the Credential which contains the client ID and client secret to be used as part of the `password` flow. type: string format: ulid x-go-name: CredentialID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid x-go-type-skip-optional-pointer: true organisationId: description: > OrganisationID is the unique identifier of the Organisation that owns the Credential. This can be different to the Connector's OrganisationID since some may be imported from Versori's public library. type: string format: ulid x-go-name: OrganisationID x-go-type: ulid.ULID x-go-type-import: path: versori.dev/vergo/ulid x-go-type-skip-optional-pointer: true clientId: description: > ClientID is the OAuth 2.0 client's identifier. This is not a sensitive value and may be presented to the user in plaintext. type: string x-go-name: ClientID clientSecret: description: > ClientSecret is the OAuth 2.0 client's secret. This is a sensitive value and will not be displayed to the user. It may be populated when updating the Credential. type: string required: - grantType MessageSeverity: type: string enum: - info - warning - error ````