Auth Tokens

Auth tokens are credentials used to authenticate with the Docker registry. They control who can push and pull images, and track usage.

Token Types

Breakwater uses two types of tokens, distinguished by their prefix:

Vendor Tokens (vtok_*)

Vendor tokens are for your own use as the software vendor:

• Push images to your repositories
• Pull any image from your repositories
• Not subject to license restrictions
• Ideal for CI/CD pipelines and development

Customer Tokens (ctok_*)

Customer tokens are given to your customers:

• Pull images only (no push access)
• Only from repositories they're licensed for
• Subject to license date ranges and tag patterns
• One customer can have multiple tokens

Creating Tokens

Create a Vendor Token

1. Navigate to Auth Tokens
2. Click New Token
3. Select Vendor as the token type
4. Enter a descriptive name (e.g., "CI Pipeline", "Release Publishing")
5. Optionally set an expiration date
6. Click Create Token
7. Copy the secret immediately - it won't be shown again

Create a Customer Token

1. Navigate to Auth Tokens
2. Click New Token
3. Select Customer as the token type
4. Select the customer from the dropdown
5. Enter a descriptive name (e.g., "Production Server", "Dev Environment")
6. Optionally set an expiration date
7. Click Create Token
8. Copy the secret immediately - it won't be shown again

You can also create customer tokens from a customer's detail page.

Token Credentials

Each token has two parts:

Username

The token identifier, automatically generated:

• Format: vtok_ or ctok_ prefix + unique identifier
• Example: vtok_abc123xyz, ctok_def456uvw
• This is not secret and can be stored in configuration files

Secret

The token password, shown only once when created:

• A random 32-character string
• Copy immediately after creation
• Cannot be retrieved later
• Treat as a sensitive credential

Using Tokens

Docker Login

docker login registry.breakwaterapp.com -u <username>
# Enter the secret when prompted for password

Or with password in command (for scripts):

echo "<secret>" | docker login registry.breakwaterapp.com -u <username> --password-stdin

In CI/CD

Store the token secret as a secret/environment variable:

# Example: GitHub Actions
- name: Login to Breakwater Registry
  run: |
    echo "${{ secrets.BREAKWATER_TOKEN }}" | \
    docker login registry.breakwaterapp.com -u vtok_yourtoken --password-stdin

Kubernetes Image Pull Secrets

kubectl create secret docker-registry breakwater-registry \
  --docker-server=registry.breakwaterapp.com \
  --docker-username=ctok_customer_token \
  --docker-password=<secret>

Token Status

Tokens have three possible statuses:

Managing Tokens

Viewing Tokens

The Auth Tokens page shows:

• Your vendor tokens: Tokens for your own use
• Customer tokens: Tokens you've created for customers

For each token, you can see:

• Token username
• Name/description
• Status
• Expiration date (if set)
• Last used date

Revoking Tokens

1. Click on the token to view details
2. Click Revoke
3. Confirm the revocation

Revoked tokens:

• Immediately stop working
• Cannot be un-revoked
• Remain visible for audit purposes

Regenerating Access

If a token is compromised or needs to be rotated:

1. Revoke the old token
2. Create a new token
3. Update all systems using the old token

There's no way to change an existing token's secret.

Token Expiration

Setting Expiration

When creating a token, you can set an expiration date:

• Tokens automatically stop working after this date
• Useful for time-limited access
• Customer tokens can be aligned with license expiration

No Expiration

Leave the expiration field blank for tokens that don't expire:

• The token remains valid until manually revoked
• Appropriate for long-term infrastructure tokens
• Requires manual rotation for security

Best Practices

Security

• Never commit secrets to version control
• Use environment variables or secret management tools
• Rotate tokens periodically, especially for production systems
• Set expirations when appropriate
• Revoke immediately when access should be removed

Naming Conventions

Use descriptive names that indicate:

• Purpose: "CI Pipeline", "Production Deployment"
• Environment: "Dev Server", "Staging", "Production"
• Owner: "John's Laptop", "Acme Corp IT Team"

Good names make it easy to audit and manage tokens.

Customer Token Management

• One token per use case: Separate tokens for different environments
• Match expirations to licenses: Align token expiration with license dates
• Document and communicate: Keep records of which tokens went to which contacts

Vendor Token Management

• Separate tokens for different systems: Don't share one token across all CI/CD
• Use short-lived tokens for sensitive systems: Production publishing pipelines
• Long-lived tokens for development: Less critical environments

Troubleshooting

"Authentication Failed"

• Verify the username is correct (including prefix)
• Verify the secret is correct (copy-paste, no extra whitespace)
• Check if the token has been revoked
• Check if the token has expired

"Access Denied" (After Successful Auth)

For customer tokens:

• Check if there's an active license for the requested repository
• Verify the license dates cover the current time
• Check if tag patterns allow the requested tag

For vendor tokens:

• Verify the repository belongs to your vendor account