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
- Sign in to the vendor portal.
- Open API tokens in the sidebar and click New API token.
- 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.
- 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
readtoken can make GET and HEAD requests. Everything else needswrite. A few GET requests change data (the first request for the signing key creates it), so they needwritetoo. - 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
readorwritescope 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.
- 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. - 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.
- Store the tokens as CI secrets and use the right one for each job:
- A
vtok_registry token fordocker push. Create it under Registry tokens. - The
vapi_API token for the API.
- A
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
readtoken unless the job writes. - Use a short expiry, and a separate token for each job or environment.
- Revoke a token the moment it leaks.