Password Ninja API - GET STARTED
API Endpoint
https://password.ninja/api/password
The Password Ninja API provides randomly generated passwords based on parameters provided via the URL.
To use this API you do not need an API key, all you need is to go to https://password.ninja/api/password
Generate Passwords
# Here is a curl example
curl \
-X GET https://password.ninja/api/password
Return Example: "chickenant40"
To get a basic password you need to make a GET call to the following URL :
https://password.ninja/api/password
As standard, the default password that is generated consists of two animals and two numbers. This password will also be at least 8 characters in length.
Customise Passwords
# Here are a few example URL's and the passwords they return
https://password.ninja/api/password?minPassLength=20
Returns: "crabbearcamelsheep74"
https://password.ninja/api/password?minPassLength=10&capitals=true
Returns: "DuckCrab27"
https://password.ninja/api/password?animals=false&colours=true&food=true&capitals=true&lettersForNumbers=100
Returns: "HamY3110w84"
The Password Ninja API has multiple parameters to generate passwords. This allows for high customisability and fine tuning of passwords generated. On the main page under advanced there is a link generator for the API. This will allow you to customise the passwords generated with a GUI instead of creating a URL manually.
The API uses standard URL encoding. To add parameters, add ?<parameter>=<value> to the end of the URL.
If you want to pass more than one parameter then use an "&" between parameters. ?<parameter1>=<value>&<parameter2>=<value>
The table below shows the parameters that can be added to the URL to generate different types of passwords. For the Boolean parameters, you only need to pass "true" if you want to use them, if not, they do not need to be included in the URL.
Most values are set to false or 0 by default, however, the ones that do not follow this rule have the default values shown in bold.
URL PARAMETERS
| Field | Type | Description |
|---|---|---|
| minPassLength | Integer | (optional) Minimum length of password (range from 8 to 20) Default is set to 8 |
| animals | Boolean | (optional) Use the animals word list. Default is set to true |
| instruments | Boolean | (optional) Use the instruments word list |
| colours | Boolean | (optional) Use the colours word list |
| shapes | Boolean | (optional) Use the shapes word list |
| food | Boolean | (optional) Use the food word list |
| sports | Boolean | (optional) Use the sports word list |
| transport | Boolean | (optional) Use the transport word list |
| symbols | Boolean | (optional) Add a symbol to the end of the password |
| capitals | Boolean | (optional) Capitalise each word |
| numAtEnd | Integer | (optional) The amount of numbers to add at the end of the password (range from 0 to 5) Default is set to 2 |
| randCapitals | Boolean | (optional) Randomly capitalise some of the letters in the password |
| lettersForNumbers | Integer | (optional) Set the chance for letters to be replaced with numbers that look like them e.g. e -> 3 or o -> 0. (range from 0 to 100) |
| numOfPasswords | Integer | (optional) Set the number of passwords that are generated. Default is set to 1 |
| maxLength | Integer | (optional) Set the maximum length of a password. Default is set to 20 |
| excludeSymbols | String | (optional) Exclude certain symbols using the following keys e = ! d = $ p = % s = * f = . h = # a = @ Usage example: excludeSymbols=eh The above excludes ! and # |
| lettersForSymbols | Integer | (optional) Set the chance for letters to be replaced with symbols that look like them e.g. a -> @ or i -> !. (range from 0 to 100) excludeSymbols also applies to this feature |
Use With PowerShell
Example PowerShell Commands:
(Invoke-WebRequest -Uri "https://password.ninja/api/password" | Select-Object -ExpandProperty content)
Returns: ["dogbee91"]
(Invoke-WebRequest -Uri "https://password.ninja/api/password?minPassLength=20" | Select-Object -ExpandProperty content) -replace '[]" []', ''
Returns: monkeyparrotbughawk65
(Invoke-WebRequest -Uri "https://password.ninja/api/password?minPassLength=10&capitals=true" | Select-Object -ExpandProperty content) -replace '[]" []', ''
Returns: HawkBird80
(Invoke-WebRequest -Uri "https://password.ninja/api/password?animals=false&colours=true&food=true&capitals=true&lettersForNumbers=100" | Select-Object -ExpandProperty content) -replace '[]" []', ''
Returns: Gr3yGrap323
$uri = "https://password.ninja/api/password?numAtEnd=1&numOfPasswords=1&animals=false&shapes=true"
Invoke-WebRequest $uri | Select -Expand Content | ConvertFrom-Json
Returns: circlesquare4
$uri = "https://password.ninja/api/password?numAtEnd=1&numOfPasswords=1&animals=false&shapes=true"
Invoke-RestMethod $uri
Returns: circlesquare8
# Two lines to make 100 passwords and store them in a CSV
$passwords = ((Invoke-WebRequest -Uri "https://password.ninja/api/password?numOfPasswords=100" | Select-Object -ExpandProperty content) -replace "[] []", "").split(",")
for ($i = 0; $i -lt $passwords.Length; $i++){$passwords[$i] | Add-Content C:\100passwords.csv}
Returns: File made in C:\ with 100 default passwords
You can use the Password Ninja API in your PowerShell scripts. In this section I will give an example command, it's output, and the possible use case.
Generating Single Passwords
The example command I am going to use is (Invoke-WebRequest -Uri "<API URL>" | Select-Object -ExpandProperty content) -replace '[]" []', ''
What this command does is use the cmdlet "Invoke-WebRequest" to return the content of the URL entered and pipe it into "Select-Object" to extract the password from the page.
Once the password has been extracted, the replace parameter is used to remove the quotes and sqaure brackets from around the password, this then finally displays the plaintext password.
Generating Multiple Passwords
Another example with PowerShell is generating multiple passwords at once. In the next example the code will generate a set number of passwords into a CSV file in a target location.
$passwords = ((Invoke-WebRequest -Uri "<API URL WITH numOfPasswords PARAMETER>" | Select-Object -ExpandProperty content) -replace "[] []", "").split(",")
This code works by sending a request for the set number of passwords in the URL and then processing the output into a CSV file.
PLEASE NOTE - The maximum number of passwords that can currently be generated is around 30,000. Any more than this can result in a 504 Error.
for ($i = 0; $i -lt $passwords.Length; $i++){$passwords[$i] | Add-Content <TARGET FILE PATH\FILENAME.csv>}
Change Log
September 12th 2024
1. Added ability to replace letters with symbols. The exclude symbols field also applied to this feature
2. Added @ symbol exclusion option for the API due to it being used in the replace letters with symbols feature
3. Fixed bug where ban list wasn't applying to passwords
4. Fixed a bug where capital letters were not taken into account when replacing them with numbers
5. Fixed API using the old word lists when no options were provided
September 11th 2024
There have been a few changes made based on suggestions from the community. Please find the changes listed below:
1. Bug fixed where browser would freeze if min and max length were set as the same
2. Removed "white" "yellow" "black" "brown" from the colour set
3. Removed "pig" "monkey" "cow" "ape" from the animals set
4. Added a ban list for the following numbers: 69, 420, 666
5. Added exclude symbols to the API (see URL PARAMETERS for more details)