Set the selected entity

POST

/selected-entities

Sets (or switches) the currently active entity for the authenticated identity. Only one entity can be selected at a time per identity — calling this endpoint again with a different entity_id replaces the previous selection.

The identity must have an active resource-access record for the target entity to select it. This endpoint is JWT-only; secret API key authentication is not supported because entity selection is a session-scoped, user-driven action.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

The selected entity was set or updated successfully.

Bodyapplication/json

🟠400

🟠401

🟠403

Request Example

Shell

JavaScript

Java

Swift

curl --location '/selected-entities' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "entity_id": "01JABC1234567890ABCDEFGHIJ"
}'

Response Example

200 - Entity selected for the first time

{
    "message": "Entity selected successfully",
    "status": "success",
    "data": {
        "id": "01JSEL1234567890ABCDEFGHIJ",
        "identity_id": "01JIDENT234567890ABCDEFGHI",
        "entity_id": "01JABC1234567890ABCDEFGHIJ"
    }
}

Modified at 2026-08-06 16:06:15

Retrieve an entity

Retrieve public metadata for the authenticated entity