API Authentication

This page provides detailed technical reference for authenticating with the WP Engine Customer API. For a more beginner-friendly guide, see the Authentication Getting Started Guide.

Authentication Method

The WP Engine Customer API uses Basic Authentication, a simple and widely supported authentication scheme. The authentication flow works like this:

1. Client prepares the authentication:

   • Combines API username and password with a colon (username:password)
   • Base64 encodes the combined string
   • Adds “Basic ” prefix to create the Authorization header

2. Client makes API request:

   • Includes the Authorization header
   • Server validates the credentials

3. Server responds:

   • Success (200 OK): Returns requested data
   • Failure (401 Unauthorized): Invalid credentials

To authenticate your requests, you’ll need:

• API username
• API password

Getting Your Credentials

1. Log in to the WP Engine User Portal
2. Navigate to API Access in the left sidebar
3. Click “Generate Credentials” if you don’t have any
4. Copy your API username and password

Note: Keep these credentials secure. They provide access to your WP Engine resources.

Using Basic Auth

To authenticate your API requests, include your credentials in the Authorization header using Basic Authentication. The header should be constructed as follows:

1. Combine your API username and password with a colon: API_USER_ID:API_USER_PASSWORD
2. Base64 encode this string
3. Prefix with “Basic ” (note the space)

Here’s how to authenticate your requests in different programming languages:

cURL

curl -X GET "https://api.wpengineapi.com/v1/user" \
  -u "API_USER_ID:API_USER_PASSWORD"

Note: cURL’s -u flag handles the Base64 encoding automatically

PHP

$client = new GuzzleHttp\Client();
$auth = base64_encode('API_USER_ID:API_USER_PASSWORD');

$response = $client->get('https://api.wpengineapi.com/v1/user', [
    'headers' => [
        'Authorization' => 'Basic ' . $auth
    ]
]);

Python

import base64
import requests

auth = base64.b64encode('API_USER_ID:API_USER_PASSWORD'.encode()).decode()

response = requests.get(
    'https://api.wpengineapi.com/v1/user',
    headers={'Authorization': 'Basic ' + auth}
)

Node.js

const axios = require('axios');

const auth = Buffer.from('API_USER_ID:API_USER_PASSWORD').toString('base64');

const response = await axios.get('https://api.wpengineapi.com/v1/user', {
    headers: { 'Authorization': 'Basic ' + auth }
});

Testing Authentication

To verify your authentication credentials are working correctly, you can make a request to the /user endpoint. This endpoint returns information about the authenticated user:

Request

curl -X GET "https://api.wpengineapi.com/v1/user" \
  -u "API_USER_ID:API_USER_PASSWORD"

Success Response

{
  "id": "fd8e24a5-1f16-4b80-af5f-d748bcc9e64d",
  "first_name": "Joe",
  "last_name": "Smith",
  "email": "joe@gmail.com",
  "phone_number": "123456789"
}

Error Response

{
  "message": "Bad Credentials"
}

Error Responses

When authentication fails, you’ll receive one of these responses:

Status Code	Description	Solution
401	Bad Credentials	Verify your API username and password are correct
429	Too Many Requests	Wait before retrying (rate limit exceeded)

Environment Setup

Here’s how to securely store and use your API credentials in different environments:

Laravel

.env

WPE_API_USER=your_api_username
WPE_API_PASSWORD=your_api_password

// config/services.php
'wpengine' => [
    'username' => env('WPE_API_USER'),
    'password' => env('WPE_API_PASSWORD'),
]

Express

.env

WPE_API_USER=your_api_username
WPE_API_PASSWORD=your_api_password

// config.js
require('dotenv').config();

module.exports = {
    wpe: {
        username: process.env.WPE_API_USER,
        password: process.env.WPE_API_PASSWORD
    }
}

Django

.env

WPE_API_USER=your_api_username
WPE_API_PASSWORD=your_api_password

# settings.py
from decouple import config

WPE_API = {
    'username': config('WPE_API_USER'),
    'password': config('WPE_API_PASSWORD')
}

Security Best Practices

1. Protect Your Credentials

   • Never expose your API credentials in client-side code
   • Don’t commit credentials to version control
   • Use environment variables to store credentials
   • Rotate credentials if they’re compromised
   • Use secrets management services in production

2. Use HTTPS

   • Always make API requests over HTTPS
   • The API will reject non-HTTPS requests
   • Verify SSL/TLS certificates

3. Implement Rate Limiting

   • Add retry logic with exponential backoff
   • Handle 429 responses appropriately
   • Monitor your API usage
   • Consider using a circuit breaker pattern

4. Minimal Scope

   • Use accounts with minimal necessary permissions
   • Create separate credentials for different applications
   • Regularly audit API access
   • Implement proper logging for API calls

Troubleshooting Guide

Common authentication issues and their solutions:

Issue	Possible Cause	Solution
401 Unauthorized	Incorrect credentials	Double-check username and password, ensure no whitespace
401 Unauthorized	Expired credentials	Generate new credentials in User Portal
429 Too Many Requests	Rate limit exceeded	Implement exponential backoff, reduce request frequency
Connection failed	HTTPS not used	Ensure requests use https:// protocol
Base64 encoding issues	Special characters	Use proper encoding function for your language
”Basic” prefix missing	Incorrect header format	Include “Basic ” prefix with space in Authorization header

Debugging Tips

1. Test credentials with cURL first
2. Use API monitoring tools like Postman
3. Check request headers in browser dev tools
4. Verify Base64 encoding with online tools
5. Enable debug logging in your HTTP client

Next Steps

• Learn about Pagination
• Explore the API Reference
• Try the Quick Start Guide