Licenses

Licenses grant customers access to pull images from your repositories. Each license connects a customer to a product for a specific time period, with optional restrictions on which image versions they can access.

What is a License?

A license in Breakwater defines:

  • Who: Which customer has access
  • What: Which product (and its repositories) they can access
  • When: The valid date range for access
  • Which versions: Optional tag pattern restrictions

When a customer attempts to pull an image, Breakwater checks their licenses to determine if the pull should be allowed.

Creating a License

  1. Navigate to a customer's detail page
  2. Click New License
  3. Fill in the license details:
    • Product: The product to license
    • Starts At: When the license becomes active
    • Expires At: When the license ends
    • Status: The license state
    • Tag Pattern: Optional version restrictions
  4. Click Create License

License Fields

Product

Select which product to license. The customer will gain access to all repositories linked to this product.

Starts At

The date and time when the license becomes active. Pulls attempted before this date will be denied.

Expires At

The date and time when the license expires. Pulls attempted after this date will be denied.

Status

Licenses have four possible statuses:

Status Description
Pending License is created but not yet active
Active License is currently valid and usable
Expired License has passed its expiration date
Cancelled License was manually terminated

A license must be Active and within its date range for pulls to succeed.

Changing status

A new license starts as Pending or Active. After that, a license can move only along these paths:

From To
Pending Active, Cancelled
Active Cancelled
Expired Active (a renewal: set Expires At in the future in the same edit), Cancelled
Cancelled Nothing. Issue a new license instead

A license can only be made Active with an Expires At in the future. Nobody sets Expired by hand: a license expires when its Expires At passes. Nothing moves back to Pending; an active license with a future Starts At simply doesn't allow pulls until then. The status menu offers only the statuses the license can move to, and the API and MCP tools refuse other changes with a validation error.

Tag Pattern

Optional field to restrict which image tags the customer can pull. Leave blank to allow all tags.

See Tag Patterns for detailed pattern syntax and examples.

License States

Active Licenses

For a license to allow image pulls, all conditions must be met:

  1. Status is Active
  2. Current date is on or after Starts At
  3. Current date is before Expires At
  4. Requested tag matches Tag Pattern (if set)

Pending Licenses

A license with Pending status won't allow pulls, even if within the date range. Use pending status for:

  • Licenses awaiting payment confirmation
  • Licenses that should switch on by themselves: a pending license is activated automatically when its Starts At date arrives

Expired Licenses

Licenses automatically become expired when past their expiration date. To renew an expired license, set Expires At in the future and its status to Active in the same edit.

Cancelled Licenses

Manually cancel licenses when:

  • A customer requests early termination
  • Payment issues require revoking access
  • You need to immediately stop access

Cancelling is permanent: a cancelled license's status can't be changed again. Create a new license instead.

Managing Licenses

Viewing Licenses

From a customer's detail page, you can see all their licenses with:

  • Product name
  • Status
  • Date range
  • Tag pattern (if set)

Editing Licenses

  1. Click on a license to view details
  2. Click Edit
  3. Update the fields
  4. Click Update License

Common edits include:

  • Extending the expiration date for renewals
  • Adding or changing tag patterns
  • Updating status

Deleting Licenses

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

Consider using Cancelled status instead of deleting, to maintain a record of the license.

Common Scenarios

New Customer Purchase

  1. Create the customer account
  2. Create an Active license
  3. Set Starts At to today (or purchase date)
  4. Set Expires At to the end of their subscription period

License Renewal

  1. Edit the existing license
  2. Extend the Expires At date (if the license has already expired, also set its status to Active)

Or create a new license for the new period.

Version-Restricted License

Use tag patterns to limit access:

  • ~> 1.0 - Access to any 1.x version
  • <= 2.5 - Access up to version 2.5
  • *-lts - Access only to LTS releases

Immediate Access Revocation

  1. Edit the license
  2. Change status to Cancelled

This immediately prevents any further pulls.

License Keys

Each license can also produce a signed license key that your software verifies offline. You can attach your own claims (seats, features) to a license and Breakwater signs them into the key. See License Keys.

Multiple Licenses

A customer can have multiple licenses for:

  • Different products: Access to multiple products
  • Same product: Overlapping or sequential license periods

When pulling, Breakwater checks if any active license grants access to the requested image.

Best Practices

Date Management

  • Set realistic expiration dates aligned with billing cycles
  • Use calendar reminders for renewal discussions
  • Consider grace periods for renewal processing

Tag Patterns

  • Use tag patterns to match your versioning strategy
  • Communicate version restrictions clearly to customers
  • Update patterns when releasing new major versions

Status Workflow

  • Start licenses as Pending if waiting for payment
  • Activate only after confirmation
  • Use Cancelled instead of deleting for audit trails
Last updated November 21, 2026