API Documentation

Overview

The Password Generation Service provides a flexible solution for creating secure passwords or memorable passphrases. It offers numerous customization options and includes an evaluation of the generated password's strength.

Base URL: https://motdepasse.app/api/generate-password
Method: POST
Auth Required: Yes (API Key in header)
Data Format: JSON

Authentication

All requests must include a valid API key in the headers.

X-API-KEY: your-api-key

Request Structure

{
  "length": number,
  "includeUppercase": boolean,
  "includeLowercase": boolean,
  "includeNumbers": boolean,
  "includeSymbols": boolean,
  "usePassphrase": boolean,
  "wordCount": number,
  "wordSeparator": string
}

Parameters

Standard Password Mode

• length: Password length

  • Type: number
  • Required if usePassphrase is false
  • Range: 4-32 characters
  • Example: 16

• includeUppercase: Include uppercase letters (A-Z)

  • Type: boolean
  • Default: false
  • Example: true

• includeLowercase: Include lowercase letters (a-z)

  • Type: boolean
  • Default: true
  • Example: true

• includeNumbers: Include numbers (0-9)

  • Type: boolean
  • Default: false
  • Example: true

• includeSymbols: Include special characters (!@#$%^&*()_+-=[]{}|;:,.<>?)

  • Type: boolean
  • Default: false
  • Example: true

Passphrase Mode

• usePassphrase: Use passphrase mode

  • Type: boolean
  • Default: false
  • Example: true

• wordCount: Number of words in the passphrase

  • Type: number
  • Required if usePassphrase is true
  • Range: 2-10 words
  • Example: 4

• wordSeparator: Separator between words

  • Type: string
  • Default: "-"
  • Example: "_"

Responses

Success (200 OK)

Example Response for Standard Password

{
  "password": "xK9#mP2$vL5nQ8",
  "strength": "strong"
}

Example Response for Passphrase

{
  "password": "Correct-Horse-Battery-Staple-42!",
  "strength": "veryStrong"
}

The strength field can have the following values:

• "weak": Low strength
• "medium": Medium strength
• "strong": High strength
• "veryStrong": Very high strength

Errors

400 Bad Request

{
  "error": "Invalid length (4-64)"
}

{
  "error": "Invalid word count (2-10)"
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

405 Method Not Allowed

{
  "error": "Method Not Allowed"
}

Password Strength Calculation

For Standard Passwords

Strength is calculated according to the following criteria:

1. Weak if:

   • Length < 8 characters OR
   • Only one type of character used

2. Medium if:

   • Length 8-11 characters AND
   • At least 2 character types AND
   • Includes numbers or symbols

3. Strong if:

   • Length 12-15 characters AND
   • At least 3 character types AND
   • Includes numbers or symbols

4. Very Strong if:

   • Length ≥ 16 characters AND
   • All character types AND
   • Includes numbers and symbols

For Passphrases

Strength is calculated according to the following criteria:

1. Weak if:

   • Less than 3 words

2. Medium if:

   • 3 words without extras

3. Strong if:

   • 4 words without extras OR
   • 3 words with numbers or symbols

4. Very Strong if:

   • 4+ words with numbers or symbols

Usage Examples

Example 1: Generating a Strong Password

const request = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your-api-key'
  },
  body: JSON.stringify({
    length: 16,
    includeUppercase: true,
    includeLowercase: true,
    includeNumbers: true,
    includeSymbols: true
  })
};

fetch('https://motdepasse.app/api/generate-password', request)
  .then(response => response.json())
  .then(data => console.log(data));

Example 2: Generating a Passphrase

const request = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'your-api-key'
  },
  body: JSON.stringify({
    usePassphrase: true,
    wordCount: 4,
    wordSeparator: "-",
    includeNumbers: true,
    includeSymbols: true
  })
};

fetch('https://motdepasse.app/api/generate-password', request)
  .then(response => response.json())
  .then(data => console.log(data));

Security Recommendations

1. Mode Selection

   • Passphrase for better memorability
   • Standard password for specific system constraints

2. Recommended Length

   • Passwords: minimum 12 characters
   • Passphrases: minimum 4 words

3. Composition

   • Use all available character types
   • Avoid predictable patterns
   • Include numbers and symbols when possible

Limitations and Considerations

• Maximum length of 64 characters for standard passwords
• Maximum 10 words for passphrases
• Predefined word list for passphrases
• Maximum 100 requests per minute per API key
• Generated passwords are not stored

Best Practices

1. Security

   • Never transmit passwords in plain text
   • Use HTTPS for all communications
   • Don't store generated passwords in plain text

2. Usage

   • Generate a new password for each account
   • Use the appropriate mode based on context
   • Verify compatibility with the target system

3. Performance

   • Group requests when possible
   • Cache results temporarily if needed
   • Plan for fallback in case of unavailability

Support

• Email: support@motdepasse.app
• API Status: https://motdepasse.app/status