API Authentication

The Breakwater vendor API uses API tokens, sent as a Bearer credential. An API token is separate from the registry tokens you use with docker login.

Create an API token

  1. Sign in to the vendor portal.
  2. Open API tokens in the sidebar and click New API token.
  3. Name the token, choose a scope and an expiry, and confirm with your password (and two-factor code, if you have one on). If your vendor uses single sign-on, you sign in again through your identity provider instead.
  4. Copy the token. It starts with vapi_ and is shown once.
Setting Choices
Scope read (list and get) or write (also create, update and delete; includes read)
Expiry 30, 90 (the default) or 365 days. There is no token that never expires

Each person can have up to 25 usable tokens per vendor. Breakwater emails the token's owner 7 days before it expires.

Make a request

curl -H "Authorization: Bearer vapi_..." \
  https://app.breakwaterapp.com/api/v1/vendor/products

A token acts as its owner

A token belongs to one user on one vendor. Every request is checked as that user, with the role they have now:

  • Roles. The vendor portal's rules apply. Reading needs the viewer role, and changing things needs the member role or higher. Demoting a user changes what their tokens can do on the next request.
  • Scopes. A read token can make GET and HEAD requests. Everything else needs write. A few GET requests change data (the first request for the signing key creates it), so they need write too.
  • Leaving. A token stops working when its owner leaves the vendor, and when it expires or is revoked.
  • Vendor requirements. The vendor's active subscription, two-factor requirement and single sign-on requirement apply to the token's owner.

You can revoke your own tokens from the API tokens page; vendor admins and owners can revoke anyone's.

Agent connections

An AI agent that connects to the MCP server through the consent page gets a connection, not a token. It appears on the API tokens page next to your tokens, marked Agent connection, with the app's name, where it sends you back, and who published its details ("Details published by a host" or "Self-described").

  • It is not an API token. A connection has no vapi_ secret. The app holds short-lived OAuth credentials that work only on the MCP endpoint (/mcp). The REST API refuses them, and the MCP endpoint refuses OAuth credentials issued for anything else.
  • It acts as you. Roles, scopes, the vendor's subscription, two-factor and single sign-on requirements apply exactly as for a token. A connection has the read or write scope you chose when you approved it.
  • It ends. A connection lasts 90 days, and ends sooner after 30 days unused or when you leave the vendor. Revoke it from the API tokens page and the agent loses access right away. It counts toward the same limit of 25 tokens and connections.
  • A vapi_ token also works on /mcp. Use one for CI and other agents that can't open a browser. See Connecting AI Agents (MCP).

Owners can turn agent connections off in Settings. That blocks /mcp and the consent page for the whole vendor, but doesn't affect the REST API or API tokens.

Errors

Authentication and authorization errors are problem details with a code and a detail:

Status code Meaning
401 registry_token_not_accepted You sent Basic auth or a vtok_/ctok_ token. Registry tokens don't work on the API
401 invalid_token The token is missing, malformed, unknown, expired or revoked, or its owner is no longer on the vendor. The message doesn't say which
403 insufficient_scope The token lacks the scope the request needs. The body includes required_scope
403 forbidden The owner's role is too low, for example This needs the member role. The body includes required_role when one role would allow it
403 subscription_required The vendor has no active subscription
403 two_factor_required The vendor requires two-factor and the owner hasn't set it up in the portal
403 sso_required The vendor requires single sign-on and the owner has no identity on it
{
  "type": "https://www.breakwaterapp.com/docs/api/errors#insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This needs a token with the write scope.",
  "code": "insufficient_scope",
  "required_scope": "write"
}

Rate limits

Requests are limited per vendor, across all of its API tokens. Responses that reach an endpoint carry X-RateLimit-Limit, and X-RateLimit-Remaining and X-RateLimit-Reset too once the limiter has counted the request. Refusals from the authentication, access (subscription, two-factor, single sign-on), scope and role checks carry none of them. A 429 carries all three and Retry-After. Requests with no usable token share a separate limit of 30 a minute per IP address. See Rate Limiting.

Token types

Prefix Type Use
vapi_ API token The vendor API (/api/v1/vendor) only
vtok_ Registry token (vendor) docker login, pushing and pulling images. The API refuses it
ctok_ Registry token (customer) Pulling images, and the customer API the breakwater CLI uses

CI recipe

Give your pipeline its own identity, so it doesn't depend on one person's account.

  1. Invite a bot user (for example ci-bot@yourcompany.com) to your vendor with the member role. Members can work with products, customers and licenses but can't manage the team, so a leaked token can do less.
  2. Sign in as the bot, open API tokens, and create a token with the write scope and an expiry. The expiry reminder goes to the bot's email, so forward that mailbox to someone who will renew the token.
  3. Store the tokens as CI secrets and use the right one for each job:
    • A vtok_ registry token for docker push. Create it under Registry tokens.
    • The vapi_ API token for the API.
echo "$REGISTRY_TOKEN_SECRET" | docker login registry.breakwaterapp.com -u "$REGISTRY_TOKEN_USER" --password-stdin
docker push registry.breakwaterapp.com/yourco/app:1.4.0

curl -X POST -H "Authorization: Bearer $BREAKWATER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"customer": {"name": "Acme Corp"}}' \
  https://app.breakwaterapp.com/api/v1/vendor/customers

If your vendor requires single sign-on or two-factor, the bot user has to meet that requirement too.

Security best practices

  • Store tokens in a secrets manager, never in version control.
  • Use a read token unless the job writes.
  • Use a short expiry, and a separate token for each job or environment.
  • Revoke a token the moment it leaks.
Last updated November 21, 2026