API v2 Preview/Early Releases

[smeijer]

We have a couple of releases related to our v2 API to share with you. We plan to finalize the API after the summer breaks and would love to hear your feedback.

Here is a quick update on what you can expect today.

Docs

We've added the v2 API reference to our docs. Right now, it's available as a [preview deployment](https://docs-git-feature-docs-magicbell.vercel.app/docs/api/overview) and will be deployed as more of our current SDKs migrate to the v2 API.

The OpenAPI file powering these docs can be fetched here: https://public.magicbell.com/specs/openapi.v2.json

Authentication

Authentication is going to change from our custom x-magicbell headers to a simple authentication: Bearer <jwt-token> scheme. It's already possible today to generate new tokens in the MagicBell dashboard, and make your api requests with them. To do so, go to your project, click settings, and then access tokens in the sidebar.

Note that these tokens can be used on both the new v2 and the old v1 endpoints. This doesn't mean just fewer headers; the new access tokens provide you with the option to add expiration dates and implement token rotation by adding and removing tokens via our dashboard or through the API.

So instead of calling the API with x-magicbell headers like:

curl --url 'https://api.magicbell.com/broadcasts' \
   --request 'POST' \
   --header 'accept: application/json' \
   --header 'content-type: application/json' \
   --header 'idempotency-key: magicbell-retry-c646dcea-e3c6-4321-9957-09a41722dc3b' \
   --header 'x-magicbell-api-key: <api-key>' \
   --header 'x-magicbell-api-secret: <api-secret>' \
   --data '{"broadcast":{"recipients":[{"email":"[email protected]"}], "title":"v1" }}'
   
# {"broadcast": { "id":"...","title":"v1" } }

You can now call the API as follows. Note that the v2 API does not wrap payloads or responses like the v1 API.

curl --url 'https://api.magicbell.com/v2/broadcasts' \
 --request 'POST' \
 --header 'accept: application/json' \
 --header 'content-type: application/json' \
 --header 'authorization: Bearer <token>' \
 --data '{"recipients":[{"email":"[email protected]"}], "title":"v2" }'
 
 # { "id":"...","title":"v1" }

The same applies to user-authenticated requests. Instead of using the x-magicbell-api-key and x-magicbell-user-email or x-magicbell-external-id and x-magicbell-user-hmac, it's now possible to make the requests using the authentication header. To do so, you'll need to [generate a user token](https://docs-git-feature-docs-magicbell.vercel.app/docs/api/reference#create_user_jwt) using your project token.

Note that the example above covers the v2/broadcasts endpoint, but the authentication header can also be used with v1 requests.

Again, you can find and manage your tokens on https://app.magicbell.com/ > settings > access tokens.

jwts.mp4

SDKs

We have two new typescript/javascript SDKs for you, one API wrapper, and one component library.

@magicbell/user-client

This is a javascript api wrapper to be used in the browser. It's typed with TypeScript and provides easy access to the user-authenticated endpoints on our v2 API. Think of endpoints to create and delete webpush tokens, as well as mobile push, slack, and teams tokens.

The user client is authenticated using our new JSON-web-token-based authentication scheme.

import { Client } from '@magicbell/user-client';

const sdk = new Client({ accessToken: userToken });

const input = {
  endpoint: 'https://example.com/webhook',
  keys: { auth: '<string>', p256dh: '<string>' },
};

const result = await sdk.channels.saveWebPushToken(input);

Note that this client needs a user-token, you can [create those](https://docs-git-feature-docs-magicbell.vercel.app/docs/api/reference#create_user_jwt) by making a POST request to https://api.magicbell.com/v2/jwt/user. We will be publishing new backend SDKs soon, which will make that easier.

@magicbell/in-app

The in-app SDK is a component library for the browser. It's built using [lit](https://lit.dev/), providing web components that can be used natively without a framework and with frameworks like React, Solid, Angular, Vue, Svelte, or any other framework supporting web components.

Note that you might need to render them on "client only" if your framework does not support server-rendering web components. React 19 promises improvements for handling web components, but we do provide a more native experience specifically for reacting under the @magicbell/in-app/react namespace.

For now, this library offers you a webpush-button that you can place on your site to let users subscribe to webpush notifications, but we plan to offer more buttons in upcoming versions.

import '@magicbell/in-app/css/core.css';
import '@magicbell/in-app/css/theme.css';
import '@magicbell/in-app/components/mb-webpush-button.js';

---

<mb-webpush-button access-token="<user-token>"></mb-webpush-button>

This new library's benefits include using the v2 API, not being limited by the framework of choice, and allowing for easy customizations in terms of content and styles. Simply use the browser APIs and web-native CSS.

Please find [@magicbell/in-app on npm](https://www.npmjs.com/@magicbell/in-app) while we finalize the docs.

webpushbutton.mp4

CLI

The CLI has been updated to work with project access tokens. We'll be making the token authentication the primary flow in the near future. For now, please create a token via the dashboard, and add it to your CLI using:

set -gx MAGICBELL_PROFILE some-name

magicbell config unset apiKey
magicbell config unset apiSecret
magicbell config set token $TOKEN

If you don't have our CLI installed, please do so with:

npm i -g @magicbell/cli

While the new access tokens don't require an expiration date, the CLI is a perfect case for creating a token that expires soon.

NPM Package Previews

A bit more meta, but for those who been following our GitHub, we now support preview releases of in-progress work. If you'd like to try out unreleased functionality, you can install our canary releases using commands like:

npm i https://pkg.pr.new/@magicbell/cli@322
npm i https://pkg.pr.new/@magicbell/in-app@322

The @322 refers to the pull request number that you wish to install. It always points to the last commit in that PR. The latest main is always available by via the pull-request [from MagicBella, named "next release"](https://github.com/magicbell/magicbell-js/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen+author%3Amagicbella). For the curious among us, our SDK's are open source and [available on GitHub](https://github.com/magicbell/magicbell-js).