Sign Out
End the user's VoxKey session and bring the browser back to your application, using OIDC RP-Initiated Logout.
1. Register where the user may return
VoxKey returns the browser only to an address the application registered in advance. An unregistered address is never followed.
In the admin panel: open the application → Settings → Post-logout redirect URIs → add the address → Save changes.
Through the Management API:
curl -X PATCH https://your-domain.com/api/v1/{realmUUID}/applications/{appId} \
-H "Authorization: Bearer $M2M_TOKEN" \
-H "Content-Type: application/json" \
-d '{"post_logout_redirect_uris": ["https://app.example.com/logout-callback"]}'
The list replaces the previous one. Each entry must be a full URL.
The address is compared character for character: scheme, host, port, path, trailing slash. https://app.example.com/logout-callback and https://app.example.com/logout-callback/ are two different addresses.
Machine-to-machine applications have no browser to return, so the setting is not offered for them.
2. Send the browser to the end-session endpoint
The endpoint is published in the realm's discovery document as end_session_endpoint:
GET https://your-domain.com/oauth2/{realmUUID}/logout
?id_token_hint={id_token}
&post_logout_redirect_uri=https://app.example.com/logout-callback
&state={opaque_value}
| Parameter | Required | Meaning |
|---|---|---|
id_token_hint | yes, to return to your app | The ID token VoxKey issued to this user for your application. It proves which application asks, and that the session being ended is this user's. |
post_logout_redirect_uri | no | One of the registered addresses. |
state | no | Returned to you unchanged on the redirect. |
client_id | no | If sent, must be the application the id_token_hint was issued to. |
What happens
| Request | Result |
|---|---|
Valid id_token_hint, registered post_logout_redirect_uri | Session ended, browser returned to that address with state |
Valid id_token_hint, no post_logout_redirect_uri, at least one address registered | Session ended, browser returned to the first registered address |
Valid id_token_hint, address not registered | Session ended, browser sent to the realm's sign-in page; a warning is logged |
Valid id_token_hint, nothing registered | Session ended, browser sent to the realm's sign-in page |
client_id differs from the application of id_token_hint | Refused; the session is left alone |
No id_token_hint | VoxKey cannot tell who asks, so the session is left alone and the user is asked to confirm on the realm's page. post_logout_redirect_uri is not followed. |
The last row is deliberate: a link that ends a session without proof is a link anyone can put on any page. The specification asks the provider to confirm with the user in that case, and VoxKey does.
Troubleshooting
The user always lands on the VoxKey sign-in page. The address in post_logout_redirect_uri is not registered for this application, or differs from the registered one (check the trailing slash and the scheme). VoxKey logs Logout asked for a post-logout address the client did not register for it.
The user is asked to confirm the sign-out. The request carried no id_token_hint, or one that was issued by another realm or to a different user than the one signed in. An expired id_token_hint is accepted: it still identifies who asks.