Skip to content

Commit

Permalink
updated getting started and authentication page
Browse files Browse the repository at this point in the history
  • Loading branch information
@MutiatBash
MutiatBash committed Oct 25, 2024
1 parent af4c574 commit 4e0def7
Show file tree
Hide file tree
Showing 2 changed files with 3 additions and 28 deletions.
16 changes: 2 additions & 14 deletions docs/rest_api/authentication.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,13 +44,10 @@ Using Mautic's API library with ``BasicAuth``
$contactsApi = $api->newApi('contacts', $auth, $apiUrl);
$contacts = $contactsApi->getList();
.. vale off
Plain HTTP requests

Check warning on line 48 in docs/rest_api/authentication.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Headings] 'Plain HTTP requests' should use sentence-style capitalization.

Raw Output:
{"message": "[Google.Headings] 'Plain HTTP requests' should use sentence-style capitalization.", "location": {"path": "docs/rest_api/authentication.rst", "range": {"start": {"line": 48, "column": 1}}}, "severity": "WARNING"}

Check failure on line 48 in docs/rest_api/authentication.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'http' instead of 'HTTP'.

Raw Output:
{"message": "[Vale.Terms] Use 'http' instead of 'HTTP'.", "location": {"path": "docs/rest_api/authentication.rst", "range": {"start": {"line": 48, "column": 7}}}, "severity": "ERROR"}
===================

.. vale on
1. Combine the username and password of a Mautic User with a colon ``:``. For example, ``user:password``.
2. Base64 encode this value. For example, with ``echo -n 'user:password' | base64``. This outputs something like ``dXNlcjpwYXNzd29yZA==``.
3. Add an Authorization header to each API request as ``Authorization: Basic dXNlcjpwYXNzd29yZA==``
Expand Down Expand Up @@ -80,12 +77,12 @@ There are two main flows that Mautic supports:
* - Authorization code flow
- This flow is best if you want Users to log in with their own Mautic accounts. All actions taken get registered as if the User performed them in Mautic's UI.
* - Client Credentials flow
- This flow is best for Machine-to-Machine, M2M, communications. For example, in cron jobs that run on at fixed times of the day.
- This flow is best for Machine-to-Machine, M2M, communications. For example, in Cron jobs that run on at fixed times of the day.
All actions get registered under the name that you provided in ``Settings > API Credentials``.
So if you called your API Credential ``Mautibot test``, Contacts created through the API show up as ``Contact was identified by Mautibot test [1]``, where ``[1]`` is the ID of the API Credential.


Authorization code flow
Authorization Code flow
========================

Using Mautic's API library for the Authorization Code flow
Expand Down Expand Up @@ -223,27 +220,21 @@ The response returned should be a JSON encoded string:
"refresh_token": "REFRESH_TOKEN"
}
.. vale off
Client Credentials flow

Check warning on line 224 in docs/rest_api/authentication.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Headings] 'Client Credentials flow' should use sentence-style capitalization.

Raw Output:
{"message": "[Google.Headings] 'Client Credentials flow' should use sentence-style capitalization.", "location": {"path": "docs/rest_api/authentication.rst", "range": {"start": {"line": 224, "column": 1}}}, "severity": "WARNING"}
=======================

Using Mautic's API library for the Client Credentials flow
----------------------------------------------------------

.. vale on
.. warning::

Mautic's API library doesn't have support yet for this flow, but there's an open PR that adds support: https://github.com/mautic/api-library/pull/269

.. vale off

Using plain OAuth2 for the Client Credentials flow

Check warning on line 235 in docs/rest_api/authentication.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Headings] 'Using plain OAuth2 for the Client Credentials flow' should use sentence-style capitalization.

Raw Output:
{"message": "[Google.Headings] 'Using plain OAuth2 for the Client Credentials flow' should use sentence-style capitalization.", "location": {"path": "docs/rest_api/authentication.rst", "range": {"start": {"line": 235, "column": 1}}}, "severity": "WARNING"}
--------------------------------------------------

.. vale on
To obtain a new access token, make a POST request to the access token's endpoint ``oauth/v2/token`` using the ``client_credentials`` grant type.

.. code-block:: console
Expand All @@ -264,13 +255,10 @@ The response returned should be a JSON encoded string:
"scope": ""
}
.. vale off
Authenticating the API Request

Check warning on line 259 in docs/rest_api/authentication.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Headings] 'Authenticating the API Request' should use sentence-style capitalization.

Raw Output:
{"message": "[Google.Headings] 'Authenticating the API Request' should use sentence-style capitalization.", "location": {"path": "docs/rest_api/authentication.rst", "range": {"start": {"line": 259, "column": 1}}}, "severity": "WARNING"}
==============================

.. vale on
Authenticating the API request with OAuth2 is easy. Choose one of the following methods that's appropriate for the app's needs.

Authorization header
Expand Down
15 changes: 1 addition & 14 deletions docs/rest_api/getting_started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,7 @@ Mautic provides several ``REST API`` endpoints that you can use. In the navigati

.. note::

Mautic has an API library available for PHP. You can `find it on GitHub <https://github.com/mautic/api-library>`_.

To get started easily, you can use Mautic's Postman collection:

.. image:: https://run.pstmn.io/button.svg
:target: https://app.getpostman.com/run-collection/19345380-9b7bbddc-8a4d-437a-8fc2-42b0b9823883?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D19345380-9b7bbddc-8a4d-437a-8fc2-42b0b9823883%26entityType%3Dcollection%26workspaceId%3D2c328b62-2531-4e35-a6bc-0f2995ce2df3
Mautic has an API library available for PHP. Check out the :xref:`Mautic API Library`.

Authentication
**************
Expand Down Expand Up @@ -44,13 +39,9 @@ In case of system errors, the response is a JSON encoded array similar to:
}
}
.. vale off
Mautic version check

Check warning on line 42 in docs/rest_api/getting_started.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.WordList] Use 'select' instead of 'check'.

Raw Output:
{"message": "[Google.WordList] Use 'select' instead of 'check'.", "location": {"path": "docs/rest_api/getting_started.rst", "range": {"start": {"line": 42, "column": 16}}}, "severity": "WARNING"}
********************

.. vale on
In case your API service wants to support several Mautic versions with different features, you might need to validate the version of Mautic you communicate with. Since Mautic 2.4.0, the version number is in all API response headers. The header name is ``Mautic-Version``.

With Mautic's PHP API library, you can get the Mautic version like this:
Expand All @@ -68,13 +59,9 @@ With Mautic's PHP API library, you can get the Mautic version like this:
``$version`` is in a semantic versioning format: ``[major].[minor].[patch]``. For example: ``2.4.0``. If you'll try it on the latest GitHub version, the version has ``-dev`` at the end. Like ``2.5.1-dev``.

.. vale off
API Rate limiter cache

Check warning on line 62 in docs/rest_api/getting_started.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Google.Headings] 'API Rate limiter cache' should use sentence-style capitalization.

Raw Output:
{"message": "[Google.Headings] 'API Rate limiter cache' should use sentence-style capitalization.", "location": {"path": "docs/rest_api/getting_started.rst", "range": {"start": {"line": 62, "column": 1}}}, "severity": "WARNING"}
**********************

.. vale on
You can configure rate limiter cache in ``config/local.php``, which defaults to the filesystem:

.. code-block:: php
Expand Down

0 comments on commit 4e0def7

Please sign in to comment.