Private Packages

Appearance

Tokens ​

Tokens are the credentials that allow Composer to authenticate with Private Packages and download your premium plugins and themes. This guide covers everything you need to know about creating, managing, and using tokens.

What Are Tokens? ​

Tokens are secure, randomly generated strings that serve as passwords for baisc Composer authentication. They provide:

  • Secure Access: Long, random strings that are difficult to guess
  • Scoped Permissions: Access only to selected packages within a specific workspace
  • Revocability: Can be revoked without affecting other projects

Best Practices Summary ​

  1. One token per project: Better security and easier management
  2. Descriptive usernames: Know what each token is for
  3. Never commit auth.json to your git repository: Add auth.json to .gitignore
  4. Use environment variables: For CI/CD and deployment
  5. Revoke when done: Remove tokens for decommissioned projects
  6. Monitor usage: Keep track of which tokens are active

Creating Tokens ​

Step-by-Step ​

  1. Log in to Private Packages
  2. Navigate to Access → Tokens
  3. Click New token
  4. Enter a username for the access token
  5. Check all packages this token has access to
  6. Click Create

Using Tokens ​

Basic Composer Authentication ​

Configure Composer to use your token:

bash
composer config http-basic.{{workspace-slug}}.private-packages.com {{token-username}} {{token}}

Note: Replace {{workspace-slug}}, {{token-username}} and {{token}} with their respective values.

Manual auth.json Configuration ​

Alternatively, create or edit auth.json in your project root:

json
{
    "http-basic": {
        "{{workspace-slug}}.private-packages.com": {
            "username": "{{token-username}}",
            "password": "{{token}}"
        }
    }
}

Note: Replace {{workspace-slug}}, {{token-username}} and {{token}} with their respective values.

Global Local Configuration ​

Global

Configure authentication globally for all projects:

bash
composer config --global http-basic.{{workspace-slug}}.private-packages.com {{token-username}} {{token}}

Note: Replace {{workspace-slug}}, {{token-username}} and {{token}} with their respective values.

This affects all Composer projects on your system.

TIP

Use local configuration for better security and easier token management. Different projects can use different tokens.

Token Management ​

Viewing Active Tokens ​

In the Private Packages dashboard:

  1. Go to Access → Tokens
  2. See a list of all active tokens
  3. View token names and creation dates

Deactivating Tokens ​

To deactivate a token:

  1. Go to Access → Tokens
  2. Find the token you want to deactivate
  3. Toggle "Active" off

Once deactivated:

  • The token immediately stops working
  • Projects using that token can't download packages
  • You can re-activate the token later

TIP

This is a temporary measure. To make it permanent, revoke the access token completely.

Revoking Tokens ​

To revoke a token:

  1. Go to Access → Tokens
  2. Find the token you want to revoke
  3. Press the three dots at the end and press delete
  4. Confirm the action

Once revoked:

  • The token immediately stops working
  • Projects using that token can't download packages
  • You'll need to create a new token and update affected projects

When to Revoke Tokens ​

Revoke tokens when:

  • A project is decommissioned
  • A token is compromised or exposed
  • A team member leaves the project
  • You're rotating tokens for security
  • A token is no longer needed

Monitoring Token Usage ​

You can monitor how and when your tokens are being used:

  1. Go to Access → Tokens
  2. Click on the token you want to monitor
  3. Scroll to the bottom of the page to view the Activity section

The activity log shows:

  • Action: What the token was used for (e.g., fetching packages.json or downloading a package)
  • IP Address: The source IP address of the request
  • Timestamp: When the activity occurred

This helps you:

  • Verify tokens are being used as expected
  • Identify unusual activity or unauthorized access
  • Track which projects are actively using tokens
  • Audit token usage for security purposes

TIP

Regular monitoring of token activity is a good security practice, especially for tokens used in production environments.

Workspace Context ​

Tokens are workspace-specific:

  • Each workspace has its own set of tokens
  • To access packages from multiple workspaces, you need tokens from each

Multi-Workspace Projects ​

If you need packages from multiple workspaces:

  1. Add multiple repository URLs to your composer.json
  2. Configure authentication for each workspace
  3. Use separate tokens for each workspace

Troubleshooting ​

Token Not Working ​

Check the format:

json
{
    "http-basic": {
        "{{workspace-slug}}.private-packages.com": {
            "username": "{{token-username}}",
            "password": "{{token}}"
        }
    }
}

Note: Replace {{workspace-slug}}, {{token-username}} and {{token}} with their respective values.

Verify the token:

  • Check if it's been revoked
  • Ensure you copied the entire token
  • Verify you're using the correct workspace

Clear Composer cache:

bash
composer clear-cache

Composer Can't Find Packages ​

If Composer can't find your packages:

  1. Make sure the package is active for your token. Navigate to Access → Tokens → [token] → Edit
  2. Verify the repository URL in composer.json
  3. Check that packages exist in the workspace
  4. Ensure the token is from the correct workspace
  5. Try composer update to refresh package information

auth.json in Wrong Location ​

Composer looks for auth.json in:

  1. Project directory
  2. Composer home directory (~/.composer or ~/.config/composer)

Make sure it's in the right location for your use case.

Next Steps ​

  • Review Access for general authentication information
  • Check Getting Started for complete setup instructions
  • Learn about Packages available in your workspace