Create a branding preview link
POST /v1/branding:preview-link · permission branding:write
Creates a link that shows the hosted login page with the environment's current branding drafts, before they are published. The page always draws the latest drafts: change a draft and reload the page to see it. A banner marks the page as a preview and every sign-in control is turned off. Draft text overrides are shown in the page's language; they cannot change the preview banner.
The link is valid for 10 minutes and cannot be revoked; after that it returns 404. Anyone who has the link can see the draft, so share it only with the people who review the design. An environment can have at most 20 valid links at the same time.
Request
The body is optional. Without a body the page shows the environment draft only.
| Field | Type | Required | Description |
|---|---|---|---|
application_id |
string | no | Also apply this application's draft (app_…). |
org_id |
string | no | Also apply this organization's draft (org_…): its logo and primary color. |
Response
200 OK. The url is returned only in this response, with Cache-Control: no-store. A request repeated with the same Idempotency-Key returns no url and secret_redacted: true; create a new link instead.
{
"url": "https://acme.eu1.keenauth.app/u/preview?token=…",
"expires_at": "2026-10-19T12:10:00Z"
}
Errors
| HTTP | code | When |
|---|---|---|
| 400 | unknown_field |
The body has an unknown field or is not a JSON object. |
| 404 | not_found |
The application does not exist in this environment. |
| 422 | validation_failed |
application_id or org_id is not a valid ID (invalid_value). |
| 401 | unauthenticated |
The credential is missing, invalid or revoked. |
| 403 | insufficient_permissions |
The credential lacks the required permission. |
| 429 | rate_limited |
The environment already has 20 valid links, or the rate limit was exceeded; retry after the Retry-After period. |
| 503 | service_unavailable |
A dependency is temporarily unavailable; retry after the Retry-After period. |
Example
curl -X POST https://api.eu.keenauth.com/v1/branding:preview-link \
-H "Authorization: Bearer $KEENAUTH_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"application_id":"app_01jb…"}'
With the CLI:
keenauth branding preview-link --application-id app_01jb…