Official JavaScript SDK and CLI for username.dev
The complete solution for username governance.

Documentation • Get API Key • Status • Support

username.dev provides a REST API that helps platforms validate and moderate usernames at registration time. Instead of building and maintaining your own profanity filters, brand protection lists, and reserved username databases, you can use our API to get instant results on whether a username should be allowed, flagged, or blocked.

Filter brands, profanity, reserved words, and premium names with a single API call. Stop maintaining blacklists—let the API govern usernames for you.

• Features
• Packages
• Quick Start
• SDK Documentation
  • Installation
  • Usage
  • API Response
  • TypeScript Types
• CLI Documentation
  • Installation
  • Usage
  • Output Examples
• Categories
• Error Handling
• Security
• Requirements
• Support
• Contributing
• License

The username.dev API detects 19+ categories including:

This monorepo contains two packages:

Package	Description	npm
@username-dev/client	JavaScript/TypeScript SDK
username-dev	Command-line interface

Sign up at app.username.dev to get your API key.

Note: You get 1,000 free requests with no credit card required.

npm install @username-dev/client

import { UsernameClient } from '@username-dev/client';

const client = new UsernameClient({ 
  apiKey: process.env.USERNAME_DEV_API_KEY 
});

const result = await client.check('taylorswift');

if (result.isReserved) {
  console.log('Username is reserved:', result.categories);
} else {
  console.log('Username is available!');
}

# npm
npm install @username-dev/client

# yarn
yarn add @username-dev/client

# pnpm
pnpm add @username-dev/client

import { UsernameClient } from '@username-dev/client';

const client = new UsernameClient({ 
  apiKey: 'un_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' 
});

const result = await client.check('berlin');

console.log(result.username);    // "berlin" (normalized)
console.log(result.isReserved);  // true
console.log(result.isDeleted);   // false
console.log(result.categories);  // [{ category: 'city', metadata: { country: 'DE' } }]

const client = new UsernameClient({ 
  apiKey: 'un_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  baseUrl: 'https://api.username.dev' // optional, this is the default
});

interface UsernameCheckResponse {
  /** The normalized username (lowercase, whitespace removed) */
  username: string;
  
  /** Whether the username is reserved (exists in the database) */
  isReserved: boolean;
  
  /** Whether the username has been marked as deleted */
  isDeleted: boolean;
  
  /** Categories associated with this username (empty if not reserved) */
  categories: UsernameCategory[];
}

interface UsernameCategory {
  /** The category name */
  category: 
    | 'brand' | 'city' | 'country' | 'region' | 'place'
    | 'public_figure' | 'government' | 'agency' | 'institution'
    | 'system' | 'restricted' | 'dictionary'
    | 'first_name' | 'last_name'
    | 'product' | 'company' | 'organization'
    | 'event' | 'other';
  
  /** Optional metadata (e.g., country code, language) */
  metadata?: {
    country?: string;  // ISO 3166-1 alpha-2 (e.g., "DE", "US")
    lang?: string;     // Language code (e.g., "en", "de")
  };
}

All types are exported from the package:

import type { 
  UsernameClient,
  UsernameClientOptions,
  UsernameCheckResponse, 
  UsernameCategory, 
  CategoryMetadata,
  ProblemDetail 
} from '@username-dev/client';

# Install globally
npm install -g username-dev

# Or use with npx (no installation required)
npx username-dev check <username>

# Set as environment variable
export USERNAME_DEV_API_KEY=un_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Or add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
echo 'export USERNAME_DEV_API_KEY=un_live_xxx...' >> ~/.zshrc

username-dev check <username> [options]

Options:

Available username:

$ username-dev check randomstring123
✓ randomstring123 is available

Reserved username:

$ username-dev check berlin
✗ berlin is reserved
  Categories: city (DE), government (DE)

Deleted username:

$ username-dev check deleteduser
⚠ deleteduser is reserved (deleted)
  Categories: restricted

JSON output:

$ username-dev check paris --json

{
  "username": "paris",
  "isReserved": true,
  "isDeleted": false,
  "categories": [
    {
      "category": "city",
      "metadata": {
        "country": "FR"
      }
    }
  ]
}

Exit Codes:

The API detects 19+ username categories. Many categories include metadata such as:

• Country codes — ISO 3166-1 alpha-2 format (e.g., DE for Germany, US for United States)
• Language codes — ISO 639-1 format (e.g., en for English, de for German)

The SDK throws descriptive errors for common API responses. All errors follow the RFC 7807 Problem Details format.

import { UsernameClient } from '@username-dev/client';

const client = new UsernameClient({ apiKey: process.env.USERNAME_DEV_API_KEY });

try {
  const result = await client.check('username');
  // Handle result
} catch (error) {
  if (error.message.includes('[429]')) {
    // Rate limited - wait and retry
    console.log('Rate limited. Please wait before retrying.');
  } else if (error.message.includes('[402]')) {
    // Quota depleted
    console.log('Quota depleted. Purchase more requests.');
  } else if (error.message.includes('[401]')) {
    // Invalid API key
    console.log('Invalid API key. Check your credentials.');
  } else {
    // Other error
    console.error('Error:', error.message);
  }
}

Warning: Never commit API keys to version control. Always use environment variables.

1. Use environment variables for API keys:

   export USERNAME_DEV_API_KEY=un_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Add .env to .gitignore:

   echo ".env" >> .gitignore

3. Use .env files for local development:

   # .env (do NOT commit this file)
   USERNAME_DEV_API_KEY=un_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

4. Use secret management in production (e.g., AWS Secrets Manager, HashiCorp Vault, Vercel Environment Variables)

API keys follow the format: un_live_<32-character-random-string>

Example: un_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

• Node.js >= 18.0.0 (for native fetch support)
• TypeScript >= 5.0.0 (optional, for type definitions)

• Documentation: docs.username.dev
• Dashboard: app.username.dev
• Status Page: status.username.dev
• Email: [email protected]
• GitHub Issues: github.com/choraria/username-dev-js/issues

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

MIT License

Copyright (c) 2025 Sourabh Choraria

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Built with care by Sourabh Choraria

Website • Dashboard • Documentation • Status