Developers
Magic Link REST API Reference
This page is the endpoint-by-endpoint reference for the Magic Link PRO REST API. The API uses the WordPress REST API namespace kc-ml/v1 and standard WordPress authentication.
PRO feature
The REST API is available in Magic Link PRO. Requests must be authenticated as a WordPress user with the required capability.
Base URL
Replace https://example.com with your WordPress site's URL:
https://example.com/wp-json/kc-ml/v1
All examples below assume HTTPS.
Authentication
Use a WordPress Application Password with HTTP Basic Authentication.
- Edit the WordPress user that should make API requests.
- Open Application Passwords in the user profile.
- Create a password for the integration.
- Store the generated password securely.
- Send the WordPress username and application password with each API request.
The default capabilities are:
| Operation | Default capability |
|---|---|
| Create a link | edit_users |
| Revoke links | edit_users |
| List links | list_users |
| Look up an event | list_users |
The required capabilities can be changed by developers with the kc_ml_rest_write_capability and kc_ml_rest_read_capability filters.
POST /links
Creates a Magic Link for an existing WordPress user.
Capability: edit_users
Request parameters
Provide either user_id or email.
| Parameter | Type | Required | Description |
|---|---|---|---|
user_id |
integer | No | WordPress user ID. |
email |
string | No | Existing WordPress user's email address. |
If both are supplied, user_id is used first.
Example
curl -X POST "https://example.com/wp-json/kc-ml/v1/links" -u "api-user:APPLICATION_PASSWORD" -H "Content-Type: application/json" -d '{"user_id":42}'
Success response
{
"user_id": 42,
"url": "https://example.com/?magic-link=...",
"expires_in": 300
}
expires_in is the current Token Lifespan expressed in seconds.
Common error
If the supplied user cannot be found, the API returns HTTP 404 with the error code kc_ml_user_not_found.
GET /links
Returns recent audit-log records through the REST API.
Capability: list_users
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page |
integer | 1 |
Page number. |
per_page |
integer | 25 |
Number of records requested. The API caps this at 100. |
Example
curl "https://example.com/wp-json/kc-ml/v1/links?page=1&per_page=25" -u "api-user:APPLICATION_PASSWORD"
Response
{
"items": [],
"total": 0
}
items contains the matching audit-log rows. total is the total count reported by the audit logger.
GET /links/{id}
Returns one audit-log event by its numeric ID.
Capability: list_users
Example
curl "https://example.com/wp-json/kc-ml/v1/links/123" -u "api-user:APPLICATION_PASSWORD"
If the ID does not exist, the API returns HTTP 404 with kc_ml_not_found.
DELETE /links/{id}
Revokes all active Magic Links belonging to the user identified by the supplied ID.
Capability: edit_users
Important
This endpoint does not revoke only one token. The numeric path value is treated as a user ID, and all active tokens for that user are revoked.
Example
curl -X DELETE "https://example.com/wp-json/kc-ml/v1/links/42" -u "api-user:APPLICATION_PASSWORD"
Response
{
"user_id": 42,
"revoked": 2
}
revoked is the number of active links removed.
Error handling
Common errors include:
| Error code | HTTP status | Meaning |
|---|---|---|
kc_ml_user_not_found |
404 | No user matches the supplied identifier. |
kc_ml_invalid_id |
400 | The supplied ID is invalid. |
kc_ml_not_found |
404 | The requested audit-log record does not exist. |
Authentication and capability failures are handled by WordPress REST permission checks.
Security recommendations
- Use HTTPS.
- Create a separate Application Password for each external system.
- Use an account with only the capabilities required by the integration.
- Store credentials in secret storage, not source code.
- Revoke Application Passwords that are no longer needed.
- Remember that generated Magic Links provide access to the user's account until they expire or are otherwise invalidated.