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
- Navigate to a customer's detail page
- Click New License
- 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
- 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:
- Status is Active
- Current date is on or after Starts At
- Current date is before Expires At
- 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
- Click on a license to view details
- Click Edit
- Update the fields
- Click Update License
Common edits include:
- Extending the expiration date for renewals
- Adding or changing tag patterns
- Updating status
Deleting Licenses
- Click on a license to view details
- Click Delete
- Confirm the deletion
Consider using Cancelled status instead of deleting, to maintain a record of the license.
Common Scenarios
New Customer Purchase
- Create the customer account
- Create an Active license
- Set Starts At to today (or purchase date)
- Set Expires At to the end of their subscription period
License Renewal
- Edit the existing license
- 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
- Edit the license
- 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