Getting startedAuthenticationOAuth 2.0

Quickstart

Go from zero to a working OAuth flow in under 5 minutes

The Brevo CLI handles app creation, credential management, and local testing. This quickstart walks you through the fastest path to a working OAuth flow.

1

Install the CLI

$npm install -g @getbrevo/cli

Requires Node.js >= 20.15.0. Verify the installation:

$brevo --version
2

Log in to Brevo

$brevo login

The CLI prompts you to choose between browser sign-in (default) and API key. Browser sign-in opens oauth-cli.brevo.com — credentials are saved to ~/.brevo/credentials.json.

Welcome to Brevo CLI
──────────────────────────────────────
? How would you like to authenticate? Browser (sign in through your browser)
  Opening your browser to log you in...
  Waiting for login to complete (Ctrl+C to cancel)...
✓ Login complete. Credentials saved to /Users/you/.brevo/credentials.json.
✓ Authenticated as you@example.com

For non-interactive environments (CI/CD), set the BREVO_API_KEY environment variable instead of running brevo login.

3

Create your app and scaffold starter code

$brevo app init

The guided setup asks for an app name, distribution type, OAuth callback URL, and whether to scaffold starter code. Use http://localhost:3009/auth/callback as your callback URL for local development.

Brevo CLI — Quick Setup
──────────────────────────────────────
✓ Already authenticated.
  Step 2: Create your first OAuth app
? App name: my-app
? Distribution type? Private (Used exclusively by your organisation)
? OAuth callback URL — where users are sent after authorizing your app: http://localhost:3009/auth/callback
? Add another redirect URL? No
✓ App created.
  App name:      my-app
  App ID:        e22eb778-a2a8-488a-a5e8-466b6dad9385
  Client ID:     8768a0ad5801806c7946ca7c29648cc2
  Client secret: [hidden — run `brevo app credentials --reveal-secret`]
  Redirect URL 1: http://localhost:3009/auth/callback
? Generate starter code now? Yes
? Output directory: ./my-app
✓ Test app scaffolded (11 files)
    ├── src/
    │   └── oauth/
    │       ├── .env.example
    │       ├── .env.local        ← credentials written here (gitignored)
    │       ├── handler.js        ← OAuth routes
    │       ├── package.json
    │       ├── server.js         ← test server entry point
    │       └── token-store.js
    ├── .gitignore
    ├── app-config.json           ← app metadata
    ├── AGENTS.md
    ├── CLAUDE.md
    └── README.md

Your client_id and client_secret are written to src/oauth/.env.local automatically. This file is gitignored — never commit it.

4

Start the test server

Install the test server’s dependencies, then start it:

$cd my-app
$npm --prefix src/oauth install
$brevo app start oauth

Your browser opens at http://localhost:3009. Click Start OAuth Flow, sign in with a Brevo account, and your tokens appear masked in the browser — click to reveal them.

Starting oauth...
Test server running at http://localhost:3009
Opening browser...

If the port you’re using isn’t registered as a redirect URL on your app, the CLI will prompt you to add it automatically. Approve to continue — it updates your app and app-config.json in one step.

What just happened

brevo app init did three things:

  1. Registered an OAuth app on Brevo, issuing a client_id and client_secret
  2. Wrote credentials to src/oauth/.env.local (gitignored, chmod 600)
  3. Scaffolded a local Express server that implements the full authorization code flow:
    • GET /auth/login — builds the authorization URL and redirects to oauth.brevo.com
    • GET /auth/callback — validates state, exchanges the authorization code for tokens
    • GET /auth/refresh — exchanges the refresh token for a new access token

This server is a reference implementation for local testing. When you’re ready to implement OAuth in your real application, follow the Integration guide.

Works out of the box with AI coding tools. The scaffold includes CLAUDE.md (for Claude Code) and AGENTS.md (for GitHub Copilot, Cursor, and similar tools), pre-populated with the OAuth flow, endpoint reference, and how to run the server. Open the project in your editor and your AI assistant already understands it — no extra context needed.

Managing your app

$brevo app list                                           # list all apps
$brevo app credentials --app-id <id> --reveal-secret     # view credentials
$brevo app update --name "New Name"                      # update app name
$brevo app update --redirect-uri https://app.com/cb      # add redirect URL
$brevo app delete --app-id <id>                          # delete app

See the CLI reference for all commands and flags.