Authentication

Learn how to use Authentication in your MagicBell Project

Authentication

The MagicBell REST API utilizes an HTTP header based authentication using your MagicBell's project's API key and secret. Your MagicBell project's API key and secret are available in the "Settings" section of your MagicBell Admin Dashboard.

While the API key of your project can be distributed freely, do not publish the API secret.

Admin operations

All API requests that perform an admin operation (like fetch all users or create notifications) require:

  • the X-MAGICBELL-API-KEY header containing your MagicBell project's API key
  • the X-MAGICBELL-API-SECRET header containing your MagicBell project's API secret
curl https://api.magicbell.com/notifications \
  --request POST \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-API-SECRET: [MAGICBELL_API_SECRET]' \
  --data '{
    "notification": {
      "title": "Ticket assigned to you: Do you offer demos?",
      "recipients": [{
        "email": "richard@example.com"
      }]
    }
  }'

Other operations

Your users can perform some operations over their notifications (like fetch and delete them). All API requests to endpoints that perform these operations require:

  • the X-MAGICBELL-API-KEY header containing your MagicBell project's API key
  • the X-MAGICBELL-USER-EXTERNAL-ID header containing the ID of the user performing the request
  • the X-MAGICBELL-USER-HMAC header containing the computed hash for the user ID
curl https://api.magicbell.com/notifications \
  --request GET \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-USER-EXTERNAL-ID: [USER_ID]'
  --header 'X-MAGICBELL-USER-HMAC: [USER_ID_HMAC]'

On the other hand, if you identify users in your app by email, set the X-MAGICBELL-USER-EMAIL header instead:

curl https://api.magicbell.com/notifications \
  --request GET \
  --header 'X-MAGICBELL-API-KEY: [MAGICBELL_API_KEY]' \
  --header 'X-MAGICBELL-USER-EMAIL: [USER_EMAIL]'
  --header 'X-MAGICBELL-USER-HMAC: [USER_EMAIL_HMAC]'

Notice that in this scenario, you should use your API secret to compute an HMAC of the user's email, instead of the user's id.

If you set both the email and the external ID in the HTTP headers when performing a request the external ID will take precedence over the email.

If you're yet to turn to HMAC authentication for your MagicBell project, you don't have to provide the X-MAGICBELL-USER-HMAC header. However, we highly recommend turning on HMAC authentication before releasing MagicBell to your users. This will help preventing users from fetching data from other users of your app.

Edit this page