Appends a secure, time-limited permissions key (?pk=…) to a URL for a specific contact. The key allows Groundhogg to identify the contact when they click the link without requiring them to be logged in to WordPress. Used internally to build unsubscribe, confirmation, and preferences centre links. You can use it to generate one-click access links to any page for a specific contact.
Parameters
| Parameter | Type | Description |
|---|---|---|
$url | string | The base URL to append the permissions key to. |
$contact | Contact | The contact the key is generated for. |
$usage | string | A slug identifying what the key is for (e.g. 'preferences', 'invoice_download'). Default 'preferences'. |
$expiration | int | How long the key is valid, in seconds. Default WEEK_IN_SECONDS. |
$delete_after_use | bool | Whether the key should be invalidated after a single use. Default false. |
Return value
string — The URL with a ?pk=… parameter appended.
Usage
$url = \Groundhogg\permissions_key_url( 'https://example.com/my-account/', $contact );
// Custom usage, 24-hour expiry, one-time use
$url = \Groundhogg\permissions_key_url(
'https://example.com/invoice/',
$contact,
'invoice_download',
DAY_IN_SECONDS,
true
);
Example
Here’s a pseudo code example for a hypothetical invoice delivery integration.
add_action( 'my_plugin_invoice_created', 'my_plugin_email_invoice_link', 10, 2 );
/**
* Email a one-time invoice download link to a contact.
*
* @param \Groundhogg\Contact $contact
* @param int $invoice_id
*
* @return void
*/
function my_plugin_email_invoice_link( $contact, $invoice_id ) {
$base_url = add_query_arg( [ 'invoice' => $invoice_id ], home_url( '/invoices/' ) );
$secure_url = \Groundhogg\permissions_key_url(
$base_url,
$contact,
'invoice_access',
2 * DAY_IN_SECONDS,
true
);
\Groundhogg\gh_mail(
$contact->get_email(),
'Your invoice is ready',
'
Download your invoice: Click here
',
[ 'Content-Type: text/html; charset=UTF-8' ]
);
}
Was this helpful?
Let us know if this document answered your question. That’s the only way we can improve.