The 2501 CLI requires an API key to authenticate with your account and access agents. API keys are managed through the Accounts interface and provide secure access to your organizations and resources.

​
Prerequisites

Before authenticating, ensure you have:

​
Creating an API Key

API keys can only be generated through the Accounts interface:
  1. Go to accounts.2501.ai
  2. Click API Keys → New API Key
  3. Configure your key:

​
Name

A descriptive identifier for the key’s purpose. Example: dev-laptop-cli, ci-pipeline, production-automation

​
Description

Optional context about the key’s intended use or environment. Example: CLI access for development workstation

​
Expiration Date

Set when the key should automatically become invalid. Use shorter expiration periods for development keys and longer periods for production automation.

​
Organization

Scope the key to a specific organization, or leave unscoped to access all organizations in your account.
  • Scoped: Key only accesses the specified organization’s agents, hosts, and resources
  • Unscoped (default): Key can access all organizations in your account
⚠️ Important: The API key value is displayed only once after creation. Copy and store it securely—you cannot retrieve it again. If you lose a key, you must create a new one or rotate the existing key.

​
Configuring the CLI

Once you have your API key: 
@2501 set api_key YOUR_API_KEY
Replace YOUR_API_KEY with the actual key value from the Accounts interface.

​
Verify Authentication

Test your authentication: 
@2501 config
If authentication succeeds, you’ll see available specialties and configurations.

​
Managing API Keys

​
Viewing API Keys

Access the API keys drawer in Accounts to view all created keys, including name, description, creation date, expiration, organization scope, and last used timestamp. The actual key values are never displayed after initial creation.

​
Rotating API Keys

Rotation generates a new key value while maintaining the same configuration:
  1. Locate the key in the list → Rotate
  2. The new key value is displayed once
  3. The previous key is immediately revoked
⚠️ Warning: Rotation immediately invalidates the old key. Update all systems using the old key before rotation to avoid service disruption. Rotate keys periodically as a security best practice, or immediately after suspected compromise.

​
Revoking API Keys

Revocation permanently disables an API key. Locate the key → Revoke → confirm. Revoked keys cannot be restored, and any systems using them will lose API access immediately. Revoke keys that are no longer needed, potentially compromised, or associated with departing team members.

​
Security Best Practices

Rotate keys regularly (e.g., every 90 days). Use organization-scoped keys when access to a single organization is sufficient. Always configure expiration dates, especially for temporary or development keys. Remove keys that are no longer needed. Create separate keys for different purposes (development, CI/CD, production). Use unique keys for each environment or automation system. Revoke keys immediately upon suspected compromise or when team members leave. Ensure your local CLI configuration files have appropriate permissions. Never commit API keys to version control. Use different keys for personal development versus shared automation.

​
Troubleshooting

Authentication Failed Verify the API key is correctly configured with @2501 config. Check the key hasn’t expired or been revoked in the Accounts interface. Ensure you copied the complete key value without extra spaces. Try setting the key again. API Key Not Working After Creation Verify you copied the entire key value. Check that the key is scoped correctly. Confirm the expiration date hasn’t passed. Wait a few moments—new keys may take time to propagate. Lost API Key You cannot retrieve the original key value. Either rotate the existing key or create a new one, then update your CLI configuration. Organization Access Issues Check the API key’s organization scope in Accounts. Verify you have access to the organization. Create a new unscoped key if you need access to multiple organizations. ⚠️ This feature is not working as intended for the moment: keys can’t be scoped to an organization. 2501 is working on the issue. For additional support, visit our Discord community or contact hello@2501.ai.

​
Next Steps

With authentication configured, you’re ready to use the CLI:
  • Learn available commands in the Commands reference
  • Initialize your first agent
  • Execute tasks from your terminal