Overview

Authentication

There are two layers of authentication for the Maven AGI APIs.

  1. API Authentication: All API calls must include an Authorization header as well as an organization ID and an agent ID. In order for a request to be valid, the Authorization header must be correct and the calling app must be installed on the Maven agent. This insures that your agent data is only exposed to apps that you trust.

  2. User authentication: Some Maven APIs, like the main ask call, require a userId to be passed in the request. It is the app’s responsibility to ensure that the userId represents a properly authenticated user. If an app provides a user email that has not been verified, that app make leak user data. See below for more details.

API Authentication

Every API request must include the Authorization header with the value Basic <base64 encoded app id:app secret>. In addition, all requests must include X-Organization-Id and X-Agent-Id headers with the values of the organization and agent IDs respectively for the agent where the app is installed.

API calls will fail if the app is not installed in the agent.

Serverless apps will have this authorization appended automatically.

Example

$curl -X GET \
>  -u "<app id>:<app secret>" \
>  -H "X-Organization-Id: <organization id>" \
>  -H "X-Agent-Id: <agent id>" \
>  https://www.mavenagi-apis.com/v1/conversations/[conversationId]

Finding your app ID and secret

Your app ID can be found on the Settings > Environment Variables page. It is also visible in every App Studio URL.

Your app secret can be found on the Settings > Keys page. Secrets can be rotated on this page as well.

App secrets should never be exposed to the public. You should only make calls to the API from your backend.

User Authentication

For Maven APIs that require a userId, there are two main options for apps to take: providing either an anonymous or an authenticated user experience.

Anonymous user experience

If an app is unable to verify a user, it can pass in a randomly generated UUID as the userId. Ideally this userId is stored in some kind of session variable to enable event tracking, but that is not required.

Anonymous users do not have any email or phone identifiers, nor any user data associated with them. Actions or knowledge which rely on user data will have preconditions that will not be met for this anonymous experience.

Even if a user is anonymous, it is still possible to personalize this experience. The initialize call can be used to start a conversation with a system message. In this system message useful non-verified page context can be provided, including the user’s name, the page they are viewing, or any other information that will provide a more tailored experience. The LLM will have access to this information, but it will not be provided as user data for action execution nor used in precondition evaluation.

This type of experience is appropriate for public websites where your users are not logged in and are asking general questions about your company.

Authenticated user experience

If an app is capable of authenticating a user, it should create a user in Maven. This API requires either a valid email or phone number.

It is critical that the email address or phone number is verified before the user is created. Allowing a user to enter a random email via a basic form would allow them to take actions on that email’s behalf. They could get information about another user’s account, including whatever sensitive data actions make available.

Some surfaces have verified users that come from the hosting platform. For example, a Maven App integration with Slack already has a verified email address. The Slack platform has guaranteed that a user asking a question has logged in and owns their email address.

If you are integrating with your own platform, then your users are also already authenticated via your own authentication mechanisms. You can provide your existing user IDs and data to Maven when directly calling the APIs from a backend server.

Web surfaces do not have built-in user verification. They require additional work to have the hosting site securely communicate the logged in user to Maven. Without secure communication, someone can attempt to load your chat widget with fake user information.

Maven-built chat widget authentication

There are several ways to provide a secure web surface integration, and any type can be supported with a custom app on the Maven platform.

One common method is to use a JWT, and this is what will be used by the new Maven-built chat widget (in development! - Note that the existing Maven chat widget does not offer an authenticated experience).

The page hosting the chat widget is responsible for verifying a user, generating a JWT, and passing the JWT to the chat widget. This enables chat to verify that provided user data has not been tampered with and allows for an authenticated experience.

The Maven chat app is opensource, so that you can validate our security measures.

We’ll provide full details on how to generate a JWT soon!