Skip to content

Client SDK

Mezzanine Client is a Python SDK and remote CLI for Mezzanine API. It enables a user or service to remotely read or write to Mezzanine CMS using Python or the command line. For example, you can write an article in Markdown on your laptop and type a simple command to automatically upload it and create a new blog post from it on your website.

This page concerns mainly the Python SDK part of the Mezzanine Client package. You can also refer to the CLI page for information on the command line tool.


pip install -U mezzanine-client

Star the Client on Github to help support further development. You can also watch it on Github to keep track of updates.


Install Mezzanine API either locally (for development) or remotely (for production), as we need an API to connect to.

Once Mezzanine API is installed,

  1. Login to your Mezzanine CMS Admin Panel (e.g.
  2. In the menu, click OAuth > Applications
  3. Create a new application with the following details:
    App Name: Mezzanine Python Client
    App ID: id
    App Secret: secret
    Client Type: Confidential
    Grant Type: Code
    Redirect URI:

For development purposes, you can define the simple app ID and secret above, otherwise use the automatically generated ones.

Getting started

The client's Mezzanine class in the api module contains a set of methods for accessing the API. Some of the most common methods are demonstrated in the following command line interface examples:

  • List published blog posts
  • <post_id> Retrieve the specified blog post
  • Create a new blog post

Start by downloading the examples included in , or directly with wget:

$ mkdir mezzanine-client-examples &amp;&amp; cd $_ &amp;&amp; wget \ \

Allow examples to be executed without explicit python command:

$ chmod u+x posts_*.py

Prior to running the examples, export your app ID and secret to your terminal environment:

$ export MZN_ID='id'
$ export MZN_SECRET='secret'

Then run an example:

$ ./

Authorize the app

If you have previously used apps for platforms like Facebook, Google, or Twitter, then you may be familiar with the OAuth app authorization process. More specifically, the Mezzanine Client uses the latest OAuth2 code authorization flow.

The first time that the Client app attempts to access the API, it will ask you to click a link to authorize it. First you will be taken to the login page on your API website, where you should login using your Mezzanine account:

mezzanine api

Next, you will be asked if you wish to authorize the Mezzanine Client app:

mezzanine api

If you confirm the authorization request, you will be given a confirmation code, displayed similar to that below.

"args": {
    "code": "vYQqcQSHmqkezX09xh8qflGVYUw6F8",
    "state": "Euf91j3H6uEE9VQ9mWsvFC5s3eEMJt"

The confirmation code in this case is "vYQqcQSHmqkezX09xh8qflGVYUw6F8" without the speech marks and should be pasted back into the app within one hour to complete the authorization.

After successful authentication, Mezzanine Client stores the OAuth refresh token in ~/.mezzanine.cfg to prevent you needing to manually re-authenticate every time you run the app. If you wish to completely logout of the app, you can delete this file.

Now you can have fun trying some of the CLI or SDK examples!

Otherwise, if there were any issues authorizing the app, it is worth checking that you followed all the prerequisite steps. Or for help, refer to the Community section below.


Chat Room - if the room is quiet, feel free to leave a message and someone will try to get back to you.

Report a bug or feature request for the client.


  • Test suite
  • Further documentation and examples