Authentication

Mautic 支持 OAuth2 或基本身份验证 (Basic Authentication) 用于 API 身份验证。

基本身份验证

要快速开始使用 Mautic 的 API，可以使用基本身份验证。

Note

出于安全原因，Mautic 建议使用 OAuth2。 如果您仍然想使用基本身份验证，则必须首先在 Mautic UI 中的 Configuration -> API Settings 中启用它，或者直接在 config/local.php 文件中设置 'api_enable_basic_auth' => true。

启用基本身份验证后，可以在 Mautic 的 API 中使用它。

使用 Mautic API 库

请阅读 Using Basic Authentication 以与 Mautic 的 API 进行交互。

HTTP 请求

  1. 将 Mautic 用户名和密码用 : (冒号) 连接起来。 例如，user:password。

  2. 使用 Base64 编码该值。 例如，echo -n 'user:password' | base64 的结果为 dXNlcjpwYXNzd29yZA==。 输出会根据使用的具体凭据而有所不同。

  3. 在每个 API 请求中添加一个 Authorization 头。 以下是一个示例：

    curl -H "Authorization: Basic dXNlcjpwYXNzd29yZA==" https://mautic.example.com/api/contacts

OAuth2

启用 Mautic 的 API 后，管理员菜单中会显示 API 凭据 选项。 创建一个 客户端 ID (Client ID) 和 密钥 (Secret)，并在下一步中使用它们。

Note

Mautic 支持 authorization_code、refresh_token 和 client_credentials 授权类型。

Mautic 支持两种主要流程：

名称 (Name)

描述 (Description)

授权码流程 (Authorization Code flow)

如果您希望用户使用自己的 Mautic 帐户登录，则此流程最佳。 所有执行的操作都会被记录为用户在 Mautic UI 中执行的操作。

客户端凭据流程 (Client Credentials flow)

此流程适用于机器对机器 (M2M) 通信，例如 Cron 作业。

Mautic 会将所有操作注册到 Settings > API Credentials 中提供的名称下。 例如，名为 Mautibot test 的凭据会将通过 API 创建的联系人标识为 Contact was identified by Mautibot test [1]，其中 [1] 表示凭据 ID。

授权码流程

使用 Mautic API 库进行授权码流程

请阅读 Obtaining an access token 以与 Mautic 的 API 进行交互。

使用标准的 OAuth2 进行授权码流程

Tip

OAuth 过程可能很复杂。 请为您的语言使用一个 OAuth 库。 对于 PHP，Mautic 建议使用 Mautic API Library。

第一步 - 获取授权码

将用户重定向到 authorize 端点 /oauth/v2/authorize：
# Navigate to this URL in the browser, as it renders the login form
https://mautic.example.com/oauth/v2/authorize?grant_type=authorization_code

&client_id=CLIENT_ID &redirect_uri=https%3A%2F%2Fexample.com%2Fyour-callback &response_type=code &state=UNIQUE_STATE_STRING

Note

  • Line breaks in the example help distinguish the different parts of the query.

  • The state is optional but recommended to prevent CSRF attacks. It should be a uniquely generated string and stored locally in a session, cookie, and so on, so you can compare it with the returned value.

  • The redirect_uri should be URL encoded.

The URL prompts the User to log in. After the User logs in, Mautic redirects the browser to the URL defined in the redirect_uri. The redirected URL follows this structure:

https://example.com/your-callback?code=UNIQUE_CODE_STRING&state=UNIQUE_STATE_STRING

To ensure the request remains secure, compare the returned state value against the original value stored in the session.

Step two - exchange authorization code for access token

Obtain the authorization code value from the code parameter in the redirect URL from step one. Immediately POST this value to the token endpoint oauth/v2/token.

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=authorization_code&client_id=CLIENT_ID&redirect_uri=https%3A%2F%2Fexample.com%2Fyour-callback&client_secret=CLIENT_SECRET&code=UNIQUE_CODE_STRING" \
     https://mautic.example.com/oauth/v2/token
Access token response
{
    "access_token": "ACCESS_TOKEN",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": "",
    "refresh_token": "REFRESH_TOKEN"
}

Note

Store this data securely and use it to authenticate future API requests.

Refreshing tokens

The expires_in field indicates the number of seconds the access token remains valid. The code handling the authorization process should use this value to generate an expiration timestamp, for example, <?php $expiration = time() + $response['expires_in']; ?>. When the access token expires, use the refresh_token value to obtain a new one.

By default, the refresh token remains valid for 14 days. Configure this duration in Mautic under Configuration > API Settings.

  • 当应用程序在14天有效期内请求新的访问令牌时，Mautic 会自动颁发一个新的访问令牌和一个新的刷新令牌。这两个令牌从颁发之日起仍然有效 14 天。

    • 如果应用程序在刷新令牌到期之前没有请求新的令牌，请从 第一步 重新开始该过程，并将用户重定向到 Mautic 登录页面。

    • 应用程序必须监控在请求新的访问令牌时是否出现 400 Bad Request 响应。如果发生这种情况，它应该将用户再次引导至授权流程。

要获取新的访问令牌，请向令牌端点 oauth/v2/token 发送一个 POST 请求，并使用 refresh_token 授权类型。

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=refresh_token&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN" \
     https://mautic.example.com/oauth/v2/token
新的访问令牌响应
{
    "access_token": "NEW_ACCESS_TOKEN",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": "",
    "refresh_token": "REFRESH_TOKEN"
}

Note

安全地存储这些数据，并将其用于对未来 API 请求进行身份验证。

客户端凭据流程

使用 Mautic API 库进行客户端凭据流程

Warning

Mautic 的 API 库目前不支持此流程，但您可以跟踪进度，请参阅 客户端凭据支持 PR。

使用标准的 OAuth2 进行客户端凭据流程

要获取新的访问令牌，请向令牌端点 oauth/v2/token 发送一个 POST 请求，并使用 client_credentials 授权类型。

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET" \
     https://mautic.example.com/oauth/v2/token
客户端凭据响应
{
    "access_token": "NEW_ACCESS_TOKEN",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": ""
}

Note

安全地存储这些数据，并将其用于对未来 API 请求进行身份验证。

对 API 请求进行身份验证

使用 OAuth2 对 API 请求进行身份验证非常简单。选择以下方法之一。

授权头

授权头可用于所有 Mautic API 端点进行身份验证。

此方法要求 Mautic 服务器将标头传递给 PHP，或提供对 apache_request_headers() 函数的访问权限。请注意，当在 FastCGI 下运行 PHP 时，apache_request_headers() 不可用。

Authorization: Bearer ACCESS_TOKEN

其他方法

虽然推荐的方法是将访问令牌放在 Authorization: Bearer 头中，但如果您的客户端无法设置自定义头，您也可以将其包含在 POST 请求体中，使用 application/x-www-form-urlencoded 格式。避免将访问令牌放置在 URL 查询字符串中，因为服务器日志、浏览器历史记录和 Referer 头通常会记录 URL，这可能会意外地暴露您的令牌。

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "firstname=John&lastname=Smith&access_token=ACCESS_TOKEN" \
     https://mautic.example.com/api/leads/new