---
title: "Revoke portal sessions"
method: POST
path: "/v2/portal.revokeSession"
tags: ["portal"]
---

# Revoke portal sessions

`POST /v2/portal.revokeSession`

## Request

- Base URL: `https://api.unkey.com`
- URL: `https://api.unkey.com/v2/portal.revokeSession`
- Auth: HTTP bearer

Revoke every live session an end user holds on a portal.

Unreleased and subject to change without notice.

Sessions that were created but not yet opened are revoked too, so their
portal URLs stop working. Revocation is not instantaneous: session lookups
are cached briefly, so a request already in flight may still succeed.

Revoking ends existing sessions only. To keep the end user out, also stop
calling `portal.createSession` for them.

Calling this again for the same end user is safe and revokes nothing.

**Required Permissions**

Your root key must have one of:
- `portal.*.create_portal_session` (for any portal in the workspace)
- `portal.<portal_id>.create_portal_session` (for a specific portal)

It also accepts `unkey:v1:<workspace_id>:projects/<project_id>/portals/<portal_id>/sessions/*#write`,
which dashboard roles carry. Unlike `portal.createSession`, a dashboard
session can call this, not just a root key.

A root key that cannot read the portal's sessions gets **404**. One that can
read them but lacks the permission gets **403**.

## Request body

- V2PortalRevokeSessionRequestBody
  - `portal` string, required: Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `externalId` string, required: The end user's identifier in your system, as passed to `portal.createSession`. Every live session this end user holds on the portal is revoked.

## Response `200`

The end user's live sessions on the portal are revoked.

- V2PortalRevokeSessionResponseBody
  - `meta` Meta, required: Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required: A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` V2PortalRevokeSessionResponseData, required
    - `sessionsRevoked` integer, required: How many live sessions were revoked. Zero when the end user had none, including when an earlier call already revoked them.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden - Your root key can read the portal's sessions but lacks the permission to revoke them.
- `404`: No such portal, or your root key cannot read its sessions.
- `429`: Too Many Requests
- `500`: Internal server error

## Changes

- **2026-10-27** `6ed4b9847395`: 1 info
  - added the non-success response with the status `403`
- **2026-10-01** `28d66b07a72c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/portal.revokeSession/post.md)

---

[API](https://skmtc.dev/unkeyed/apis/unkey-api.md) - [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)