Password Pusher API v2
BETAComprehensive REST API documentation for integrating Password Pusher into your workflows, applications and tools.
Beta Notice: API v2 is currently in beta. While we've made every effort to ensure stability, there may be breaking changes before the final release. We welcome your feedback!
Overview
The Password Pusher API v2 provides a RESTful interface for creating, retrieving, and managing secure password pushes and requests. All API endpoints return JSON responses and use standard HTTP status codes.
Bearer Token Authentication
Secure API access with token-based authentication
JSON-Only Responses
Consistent JSON format across all endpoints
RESTful Design
Intuitive REST endpoints following best practices
Pushes & Requests
Support for one-way pushes and two-way requests
Password Generator
Create passwords, passphrases, and PINs via POST /api/v2/generate
API v2 uses Bearer token authentication. To authenticate, include your API token in the Authorization header:
Authorization: Bearer YOUR_API_TOKEN
Getting Your API Token
- Log in to your Password Pusher account
- Navigate to your API tokens page
- Generate an API token
- Copy the token and use it in your API requests
Note: Some endpoints (like retrieving a push or request, or generating a password) can be accessed anonymously. Creating requests, accessing audit logs, and managing collections require authentication. Include a Bearer token on generate requests when you need the signed-in workspace policy.
All API endpoints are prefixed with:
https://007.ranger-it.com/api/v2
Beta Availability
API v2 is currently in beta and is available on pwpush.com and self-hosted Pro editions. The API will be added to the open-source edition after it exits beta.
For self-hosted instances, use your own domain. The base URL shown above reflects the current host you're accessing.
GET /api/v2/version
Returns the current API version, application details, and a features hash describing which capabilities are enabled on this instance.
Example Request
curl -X GET https://007.ranger-it.com/api/v2/version
Example Response
{
"application_version": "2.1.0",
"api_version": "2.1",
"edition": "commercial",
"features": {
"anonymous_access": true,
"api_token_authentication": true,
"password_generator": {
"enabled": true,
"languages": ["de", "en", "es", "fr", "it"]
},
"accounts": {
"enabled": true
},
"pushes": {
"enabled": true,
"email_auto_dispatch": true,
"file_attachments": {
"enabled": true,
"requires_authentication": true
}
},
"requests": {
"enabled": true,
"email_auto_dispatch": true,
"file_attachments": {
"enabled": true,
"requires_authentication": true
}
}
}
}Features Hash
anonymous_access - Whether anonymous API usage is allowed
api_token_authentication - Bearer token authentication support
password_generator.enabled - Whether password, passphrase, and PIN generation is enabled
password_generator.languages - Supported passphrase word list languages
accounts.enabled - Whether workspace listing is available at /api/v2/workspaces (legacy path /api/v2/accounts is an alias)
pushes.enabled - Push creation and management via API
pushes.email_auto_dispatch - Email notifications on push creation
pushes.file_attachments.enabled - File attachments on pushes
pushes.file_attachments.requires_authentication - File attachments require authentication
requests.enabled - Request creation and management via API
requests.email_auto_dispatch - Email notifications on request creation
requests.file_attachments.enabled - File attachments on request responses
requests.file_attachments.requires_authentication - File attachments require authentication
POST /api/v2/generate
Creates one or more passwords, passphrases, or PINs. Authentication is optional. Anonymous requests use the core workspace (or self-hosted global) policy. Send a Bearer token to use the signed-in workspace policy, including on custom domains.
When generator configuration is disabled by policy, option overrides are ignored and only count is honored.
If password generation is disabled, the API returns 403 Forbidden.
Generation is limited to 30 requests per minute per IP address or authenticated user.
Request Body (JSON)
Send parameters at the root of the JSON object. Omitted fields fall back to the effective policy defaults.
| Parameter | Type | Description |
|---|---|---|
workspace_id
optional
|
string | Authenticated workspace to apply policy from. Also accepts account_id. Returns 401 if the caller is not a member of that workspace. |
type
optional
|
string | password, passphrase, or pin |
count
optional
|
integer (1-10) | Number of values to generate |
language
optional
|
string | Passphrase word list: en, es, fr, de, or it |
word_count
optional
|
integer (3-10) | Number of words in a passphrase |
separator
optional
|
string | String inserted between passphrase words |
capitalize
optional
|
boolean | Capitalize each passphrase word |
number
optional
|
boolean | Append digits to a passphrase |
symbol
optional
|
boolean | Append a symbol to a passphrase |
length
optional
|
integer | Password length (4–128) or PIN length (4–12) |
uppercase
optional
|
boolean | Include uppercase letters in passwords |
lowercase
optional
|
boolean | Include lowercase letters in passwords |
digits
optional
|
boolean | Include digits in passwords |
symbols
optional
|
boolean | Include symbols in passwords |
avoid_ambiguous
optional
|
boolean | Exclude ambiguous characters such as 0, O, l, and 1 |
min_digits
optional
|
integer | Minimum number of digits in a password |
min_symbols
optional
|
integer | Minimum number of symbols in a password |
charset
optional
|
string | Letter preset: ascii, latin, cyrillic, or greek. Any other value is treated as a custom character pool. |
Response Fields
| Field | Description |
|---|---|
type |
password, passphrase, or pin |
language |
Present for passphrases. The word list used to generate the result. |
entropy_bits |
Estimated strength returned in the response. See entropy as a measure of password strength. |
results |
Array of generated strings |
Example Request
curl -X POST https://007.ranger-it.com/api/v2/generate \
-H "Content-Type: application/json" \
-d '{
"type": "passphrase",
"language": "en",
"word_count": 4,
"count": 2
}'Example Response
{
"type": "passphrase",
"language": "en",
"entropy_bits": 51.7,
"results": ["Correct-Horse-Battery-Staple42", "River-Garden-Lantern-Anchor17"]
}Password Example
curl -X POST https://007.ranger-it.com/api/v2/generate \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "password",
"length": 20,
"symbols": true
}'Example: Create and Retrieve a Push
# Create a push
curl -X POST https://007.ranger-it.com/api/v2/pushes \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"push": {
"payload": "MySecretPassword123",
"expire_after_duration": 6,
"expire_after_views": 3
}
}'
# Retrieve the push
curl -X GET https://007.ranger-it.com/api/v2/pushes/fkwjfvhall92Example: Create a Request and Respond
# Create a request
curl -X POST https://007.ranger-it.com/api/v2/requests \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"request": {
"request": "Please provide the API key",
"close_after_duration": 8
}
}'
# Respond to the request
curl -X PATCH https://007.ranger-it.com/api/v2/requests/orpw2wkg00vpn0a/respond \
-H "Content-Type: application/json" \
-d '{
"request": {
"response": "The API key is: sk_live_1234567890"
}
}'Request States
The API uses standard HTTP status codes:
200 OK
Request succeeded
201 Created
Resource created
400 Bad Request
Invalid parameters
422 Unprocessable Entity
Validation errors or invalid request data
401 Unauthorized
Authentication required
403 Forbidden
Access denied
404 Not Found
Resource not found
Rate limiting is implemented to protect the API from abuse and ensure fair usage for all users. Rate limits are applied per IP address and vary depending on the type of request and endpoint.
Audit log GET requests are limited to 15 requests per minute per IP, with a burst limit of 5 requests per 10 seconds, and 30 requests per minute per authenticated user or API token.
Rate Limit Responses
When a request exceeds the rate limit, the API returns a 429 Too Many Requests status code with a Retry-After header indicating when you can retry the request.
Best Practices
- Implement exponential backoff when you receive a 429 response
- Respect the
Retry-Afterheader value - Cache responses when appropriate to reduce API calls
- Batch operations when possible instead of making many individual requests
- Monitor your application's API usage to avoid hitting limits
Note: Rate limits are designed to prevent abuse while allowing legitimate usage. If you consistently encounter rate limits, consider optimizing your integration or contacting support to discuss your use case.
Last updated: September 20, 2026