Build an app for other merchants

Goal: an app that other Bolder merchants connect to their account, such as a fulfillment tool, an ERP sync or a reporting service. Each merchant authorizes your app once; you get a token scoped to what you asked for.

For scripts that act on your own account, a personal access token is simpler. Apps can’t be listed in a public app directory yet: you share your app’s connect link with merchants yourself.

Go to start.onbolder.com/dev/credentials, sign in and create an application. Set its redirect URI (for example https://yourapp.com/callback). You get a CLIENT_ID and a CLIENT_SECRET; keep the secret on your server.

Send the merchant to authorize

GET https://auth.onbolder.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=products.read,orders.read,orders.write

Ask only for the scopes you need: each namespace (products, orders, customers, shops, hub, store, sellers, batches) has a .read and a .write scope. The table is in the API reference.

Exchange the code

Bolder redirects back to your redirect_uri with a code. Exchange it on your server:

const res = await fetch('https://auth.onbolder.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: process.env.BOLDER_CLIENT_ID,
    client_secret: process.env.BOLDER_CLIENT_SECRET,
    redirect_uri: 'https://yourapp.com/callback',
    code: req.query.code
  })
})
const { access_token, refresh_token, expires_in, scope } = await res.json()

Store both tokens with the merchant’s account in your app.

Call the API as the merchant

import { createBolder } from 'bolder-api-client'

const bolder = await createBolder({ token: access_token })
const orders = await bolder.orders.list({ status: 'pending' })

Refresh before it expires

Access tokens are temporary (expires_in is in seconds). Get a new one with the refresh token:

new URLSearchParams({
  grant_type: 'refresh_token',
  client_id: process.env.BOLDER_CLIENT_ID,
  client_secret: process.env.BOLDER_CLIENT_SECRET,
  refresh_token
})

Post it to the same /oauth/token endpoint.

Ruby apps

omniauth-bolder is the OmniAuth strategy for the authorization step:

use OmniAuth::Builder do
  provider :bolder, ENV['BOLDER_KEY'], ENV['BOLDER_SECRET'], scope: 'products.read,orders.read'
end

Server-to-server

A backend that only acts on the account that owns the application can skip the redirect and use the client credentials grant:

curl -X POST https://auth.onbolder.com/oauth/token \
  -d "grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&scope=orders.read"

The CLI reads the same credentials from BOLDER_CLIENT_ID and BOLDER_CLIENT_SECRET for use in CI.

Receive order webhooks to react to each merchant’s events.
Authentication reference: every grant type and the token response.

Build an app for other merchants

Ruby apps

Server-to-server

Next