POST /api/v1/connections/<id>/reveal-secrets returns a connection's Cloud API access token on demand. The response carries Cache-Control: no-store, every reveal is recorded in secret_reveal_events keyed to the API key id, and the endpoint is rate-limited to 60 reveals/hour per key. You don't need to cache tokens — fetch them when you need them, and the audit trail tells you who fetched what when.
What this endpoint does
Returns the long-lived system-user access token Dualhook stored when the tenant completed Embedded Signup. You then use that token to call Meta's Cloud API directly (sends, templates, media, etc.). Dualhook does not store the verify token, since you supplied that yourself at session creation.
Request
POST /api/v1/connections/:id/reveal-secrets
Authorization: Bearer dh_live_xxx
Content-Type: application/json
{ "secretTypes": ["access_token"] }
secretTypes is an array so the endpoint can return multiple secret types in the future.
Response
{
"connectionId": "conn_xxx",
"secrets": {
"access_token": "EAA..."
}
}The HTTP response carries Cache-Control: no-store so the body is never cached by intermediate proxies.
Audit log
Every reveal is recorded in the secret_reveal_events table with: API key id, timestamp, connection id, and the requested secretTypes. You can review reveal activity from the dashboard for any connection or key.
Rate limit
60 reveals per hour per API key. Dedicated scope so it does not consume the general write budget. See Rate limits.