Skip to content
OpenRelay is in early access, and the /v1 API is stable. New capabilities ship in the changelog.
PricingDashboard
GuidesAPI ReferenceCLI
API ReferenceAccount and accessAccount

The current principal and the org it acts in

Returns the calling principal (API key or user session) and the organization the request acts in, with the org's name and, for a key, its id, name and budget. For an API key that org is fixed by the key; for a session it is the active org, and availableOrgs lists every org the user belongs to. Unlike /v1/me this works for API keys and does not onboard.

Required permission

Requires the self.read permission. See Permissions for the roles and API key permissions that include it.

Command line

The orl CLI wraps this endpoint:

orl account whoami
GET
/v1/whoami

Authorization

apiKey
headerAuthorizationBearer <token>

OpenRelay API key. Send it as Authorization: Bearer or_… (legacy vl_… keys still work).

Response Body

The caller's principal + acting org

application/json
  1. response
principalType*string

Whether the caller authenticated with an API key, a user session, or the platform admin token.

Value in"api_key""user""platform_admin"
organizationId*string

The org this request acts in (fixed for a key, the active org for a session; may be empty for a session mid-onboarding).

organizationName?string
userId?string

Set for a user session.

email?string

Set for a user session.

role?string

The user's role in the acting org (session only).

platformAdmin?boolean

Whether this caller may use the /v1/admin/* surface. Absent means no, so a client that ignores the field fails closed. This is the whole answer for every principal: true for the session of an allowlisted platform admin and for the platform admin token, never for a customer API key. principalType answers a different question, how the caller authenticated, and the two do not line up: an allowlisted session is principalType "user" with platformAdmin true. Read this field, not that one, to decide what an admin surface may show.

scopes?array<string>

The API key's scopes (key principal only).

roleName?string

The role's display name (permissions enabled only).

permissions?array<string>

Every action this caller may perform in the acting organization, after its role, key restrictions and guardrails (permissions enabled, or a personal key).

keyKind?string

Key principal only.

Value in"personal""org""legacy"
ownerUserId?string

A personal key's owner.

restrictions?
key?

The API key that made the request (key principal only), so a client can warn before the key stops working. A revoked or expired key never gets here: it is refused with 401 REVOKED_API_KEY or EXPIRED_API_KEY.

availableOrgs?array<>

Every org the user belongs to (session only).

Example Request
curl -X GET 'https://api.openrelay.inc/v1/whoami'
Example Response
{  "principalType": "api_key",  "organizationId": "string",  "organizationName": "string",  "userId": "string",  "email": "string",  "role": "string",  "platformAdmin": true,  "scopes": [    "string"  ],  "roleName": "string",  "permissions": [    "string"  ],  "keyKind": "personal",  "ownerUserId": "string",  "restrictions": {    "permissions": [      "string"    ],    "models": [      "string"    ],    "endpoints": [      "string"    ],    "ipRanges": [      "string"    ]  },  "key": {    "id": "string",    "name": "string",    "prefix": "string",    "expiresAt": "2019-08-24T14:15:22Z",    "expiresInDays": 0,    "budget": {      "limitNanoUsd": 0,      "period": "lifetime",      "spentNanoUsd": 0,      "periodEndsAt": "2019-08-24T14:15:22Z"    }  },  "availableOrgs": [    {      "organizationId": "string",      "name": "string",      "role": "string",      "roleName": "string",      "permissions": [        "string"      ],      "maxKeyLifetimeDays": 0    }  ]}

Decline a pending org invite (session only) POST

Deletes the pending invite to the given organization addressed to the session's email, without joining. Returns 204 whether or not an invite existed.

Update the caller's profile PATCH

Sets the signed-in user's full name, avatar URL or default organization and returns the profile. The default must be an org the user belongs to (403 otherwise). Requires a signed-in dashboard session token; API keys cannot call this endpoint.