Authentication

MagicBell's REST API utilizes your MagicBell's project's API key and secret to authenticate requests. Your MagicBell project's API key and secret are available in the "Settings" section of your MagicBell Admin Dashboard.

Expected headers

When performing an API request, provide:

  • the X-MAGICBELL-API-KEY header containing your MagicBell project's API key
  • the X-MAGIBCELL-API-SECRET header containing your MagicBell project's API secret

Here's an example:

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?",
      "content": "Hi, can you give us a demo?",
      "category": "new_reply",
      "recipients": [{
          "email": "richard@example.com"
      }]
    }
  }'
fetch('https://api.magicbell.com/notifications', {
  method: 'POST',
  headers: {
    'X-MAGICBELL-API-KEY', 'MAGICBELL_API_KEY',
    'X-MAGICBELL-API-SECRET', 'MAGICBELL_API_SECRET',
  },
  body: JSON.stringify({
    notification: {
      title: "Ticket assigned to you: Do you offer demos?",
      content: "Hi, can you give us a demo?",
      category: "new_reply",
      recipients: [{
        email: "richard@example.com"
      }]
    }
  })
});

Some API endpoints require an additional header to identify the user whose notifications you want to read, delete, etc.

If you identify users in your app by email, provide the X-MAGICBELL-USER-EMAIL header, like this:

curl https://api.magicbell.com/notifications \
  --request GET \
  --header 'X-MAGICBELL-API-KEY: MAGICBELL_API_KEY' \
  --header 'X-MAGICBELL-USER-EMAIL: richard@example.com'
fetch('https://api.magicbell.com/notifications', {
  headers: {
    'X-MAGICBELL-API-KEY', 'MAGICBELL_API_KEY',
    'X-MAGICBELL-USER-EMAIL', 'richard@example.com',
  },
});

If you don't use emails to identify your users, provide the X-MAGICBELL-USER-EXTERNAL-ID with the ID of the user from your database:

curl https://api.magicbell.com/notifications \
  --request GET \
  --header 'X-MAGICBELL-API-KEY: MAGICBELL_API_KEY' \
  --header 'X-MAGICBELL-USER-EXTERNAL-ID: 0e8277ec'
fetch('https://api.magicbell.com/notifications', {
  headers: {
    'X-MAGICBELL-API-KEY', 'MAGICBELL_API_KEY',
    'X-MAGICBELL-USER-EXTERNAL-ID', '0e8277ec',
  },
});

Requests on behalf of your users

Your users can and will make requests to some MagicBell API endpoints to fetch their notifications, for example. To prevent users from fetching data from other users of your app, enable HMAC authentication. When HMAC is enabled, you need to provide one additional header: X-MAGICBELL-USER-HMAC.

Use your API secret to compute an HMAC of the user's email or id. Then, when performing API requests on behalf of your user, provide the X-MAGICBELL-USER-HMAC header containing the HMAC instead of the X-MAGICBELL-API-SECRET header.

curl https://api.magicbell.com/notifications \
  --request GET \
  --header 'X-MAGICBELL-API-KEY: MAGICBELL_API_KEY' \
  --header 'X-MAGICBELL-USER-EXTERNAL-ID: 0e8277ec' \
  --header 'X-MAGICBELL-USER-HMAC: USER_ID_HMAC'
fetch('https://api.magicbell.com/notifications', {
  headers: {
    'X-MAGICBELL-API-KEY', 'MAGICBELL_API_KEY',
    'X-MAGICBELL-USER-EXTERNAL-ID', '0e8277ec',
    'X-MAGICBELL-USER-HMAC': 'USER_ID_HMAC'
  }
});

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.