Customers

Customers represent the companies or individuals who purchase licenses for your products. Each customer can have multiple licenses and auth tokens.

What is a Customer?

A customer in Breakwater is an account that:

  • Receives licenses to access your products
  • Has auth tokens for pulling images from the registry
  • Tracks pull history and usage

Customers are specific to your vendor account. If the same company purchases from multiple vendors, they would have separate customer records with each vendor.

Creating a Customer

  1. Navigate to Customers in the vendor portal
  2. Click New Customer
  3. Enter the customer name
  4. Click Create Customer

Your team's owners get a "New customer added" email for each new customer, however it was created.

Your plan sets how many customers you can have: 5 on Starter, 25 on Growth, 100 on Business, and as many as you need on Enterprise. The Customers page and the dashboard show how many you've used, and from 80% of the limit (always including the last one) the Customers page warns you. At the limit, adding a customer is refused with a message saying so; remove a customer or upgrade to add more. Owners get an upgrade link that goes straight to the confirmation for the plan that lifts the limit, then back to the new customer form; anyone else is asked to get an owner to upgrade. Existing customers keep working, including after a downgrade to a plan with a lower limit. The API refuses POST /api/v1/vendor/customers at the limit with a 403 and the customer_limit_reached code, with limit and count in the body.

Creating a customer does not generate an auth token. Invite their team so they can create their own pull tokens, or create a token for them from the customer page.

On Growth and up, your customers see your logo, name and color in the portal. See Portal Branding.

Customer Details

Name

The customer name should be recognizable to you and your team. Common choices:

  • Company name: "Acme Corporation"
  • Team or department: "Acme Corp - Engineering"
  • Individual name for single-user licenses: "John Smith"

Customer Page

The customer detail page shows:

  • Licenses: All licenses issued to this customer
  • Registry tokens: Registry credentials for this customer, with who created each one
  • Recent Pulls: Latest image pulls by this customer

Customer Pull Tokens

Customers manage their own pull tokens. Once someone from the customer has accepted an invitation, any of their users can create and revoke tokens on the Tokens page of the customer portal. A customer can have up to 25 active tokens.

Each token on the customer page shows who created it:

  • An email with "(customer)" for a token a customer user created in the portal
  • An email for a token your team created in the vendor portal or the onboarding wizard, or "Deleted user" if that person was removed from Breakwater
  • "Breakwater admin" or "API" for tokens created those ways
  • Nothing for tokens created before Breakwater recorded this

Customer tokens are shared by everyone at the customer, so they keep working after their creator leaves. When the creator no longer has access (they were removed from the customer's team, or from your team for a token you created), an active token shows an amber Creator no longer has access badge so you can decide whether to revoke it. Admin, API, and older tokens never show the badge.

Removing a user from a customer opens a confirmation dialog. If they have unrevoked tokens for that customer, the dialog lists them with an Also revoke the N tokens they created checkbox. It is unchecked by default. Checking it revokes every non-revoked token that user created for this customer.

Managing Customers

Viewing Customers

The Customers page lists all your customers with:

  • Customer name
  • Number of licenses (active and total)

Click on a customer to see their complete profile.

Editing Customers

  1. Click on the customer to view details
  2. Click Edit
  3. Update the customer name
  4. Click Update Customer

Deleting Customers

  1. Click on the customer to view details
  2. Click Delete
  3. Confirm the deletion

Deleting a customer will also delete:

  • All licenses issued to that customer
  • All auth tokens for that customer

This action cannot be undone.

Customer Workflow

A typical customer setup involves:

  1. Create the customer account
  2. Issue licenses for the products they've purchased
  3. Invite their team so they can create their own pull tokens, or generate an auth token for them yourself
  4. Share credentials with the customer if you created the token

If you set up your first customer in the onboarding wizard, the customer step asks "How will this customer get access?":

  • Invite their admin to the portal (the default) asks for an email address and invites that person as the customer's admin. They accept, then create their own pull tokens. The customer, license, and invitation are created together, so an invalid email creates nothing.
  • Create a pull token and send it myself creates a token and shows its credentials once on the completion page.

Issuing Licenses

From the customer detail page:

  1. Click New License
  2. Select the product
  3. Set license dates and any tag restrictions
  4. Save the license

See Licenses for detailed information.

Creating Registry Tokens

From the customer detail page or Registry tokens section:

  1. Click New Token
  2. Select "Customer" as the token type
  3. Select the customer
  4. Give it a descriptive name
  5. Save and copy the secret

See Registry tokens for detailed information.

Sharing Credentials

After creating a customer token, you need to share the credentials with your customer. Provide them with:

  1. Username: The token username (e.g., ctok_abc123def)
  2. Password: The token secret (only shown once when created)
  3. Registry URL: registry.breakwaterapp.com

Example instructions for your customer:

# Log in to the registry
docker login registry.breakwaterapp.com -u ctok_abc123def

# Pull an image
docker pull registry.breakwaterapp.com/your-vendor/product:v1.0

Best Practices

Customer Organization

  • One customer per company: Unless you need separate tracking for different teams
  • Clear naming: Use official company names for easy identification
  • Document contacts: Keep track of who to contact at each customer (outside of Breakwater)

Token Management

  • Create descriptive token names that indicate purpose (e.g., "Production Server", "CI Pipeline")
  • Set expiration dates aligned with license periods
  • Create separate tokens for different environments or use cases
  • Revoke tokens promptly when no longer needed

License Planning

  • Issue licenses that match your sales agreements
  • Use tag patterns to control version access
  • Set realistic expiration dates and plan for renewals

Expiry reminders

Customer admins get an email 30 days and 7 days before each license expires. Reminders are on by default. The email names your vendor account and, if you've set one, your contact email, which is also used as the Reply-To address. Admins and owners can set the contact email or turn reminders off under Settings.

If you issue a newer license for the same product that starts by the time the old one expires (and grants the same or broader tags), the old license's reminders are skipped.

Activation and expiry emails

Customer admins also get an email when a license becomes active and when it expires:

  • Active: when a Pending license reaches its Starts At date and Breakwater activates it, or when you create, change or renew a license (in the portal, through the API or MCP) so that it's Active and in force now. A license saved as Active with a future Starts At gets no email, then or later; issue it as Pending if the customer should hear when it starts.
  • Expired: when an active license reaches its end date, unless a newer license replaces it.

Like the reminders, these name your vendor account and reply to your contact email. They're sent even when reminders are turned off. See Email Notifications for the membership, license, token and webhook emails.

Last updated November 21, 2026