OAuth 2.0 authorization

The $http service allows executing HTTP requests with authorization using the OAuth 2.0 protocol.

tip

The preferred way to integrate the bot with popular services that require OAuth 2.0 authorization is to use the built-in $integration service rather than $http.

Syntax

To enable OAuth 2.0 authorization, add the oauth2ResourceDetail property to the settings you pass to $http.query or $http.config. It should be an object with the following properties:

• grantType.

  caution

  Tovie Platform only supports grant types that don’t require a user to navigate to an external authorization service. For example, client_credentials is supported, while authorization_code isn’t.

• accessTokenUrl — the endpoint where Tovie Platform will submit all requests to issue or renew an access token.

• clientId issued by the resource server when registering the application.

• clientSecret issued by the resource server when registering the application.

note

oauth2ResourceDetail may contain other properties as well: their exact set depends on the resource server.

How to use

User authorization

If a bot user is the one who needs authorization, every user should use their own credentials.

state: UserName
    q!: * what [is/'s] my name *
    script:
        $temp.response = $http.query("https://example.com/api/v1/users/me", {
            oauth2ResourceDetail: {
                grantType: "client_credentials",
                accessTokenUrl: "https://example.com/oauth2/token",
                clientId: "bot",
                // The client secret should be obtained from the user.
                clientSecret: $client.secret,
                // Other properties
                parameterIncludes: { realm: "/customer" },
                tokenPrefix: "sso_1.0_"
            }
        });
    if: $temp.response.isOk
        a: Your name is {{$temp.response.data.name}}.
    else:
        a: I don’t know…

Bot authorization

If the bot itself needs authorization, it should use the same credentials for all its users.

state: Start
    q!: $regex</start>
    script:
        $http.config({
            oauth2ResourceDetail: {
                grantType: "client_credentials",
                accessTokenUrl: "https://example.com/oauth2/token",
                clientId: "bot",
                // The client secret should be saved as a project secret.
                clientSecret: $secrets.get("EXAMPLE_COM_CLIENT_SECRET"),
                // Other properties
                parameterIncludes: { realm: "/customer" },
                tokenPrefix: "sso_1.0_"
            }
        });

state: BotName
    q!: * what [is/'s] your name *
    script:
        $temp.response = $http.query("https://example.com/api/v1/apps/${botId}", {
            query: {
                botId: $request.botId
            }
        });
    if: $temp.response.isOk
        a: My name is {{$temp.response.data.name}}.
    else:
        a: I don’t know…