Whoami

SDK methods for verifying the calling API key and detecting environment drift.

The client.whoami namespace verifies the calling API key and returns caller identity, scopes, and key metadata. It also exposes platform-side environment hints so consumers can detect environment drift (dev consumer accidentally pointed at prod, etc).

SDK	Install	Namespace
TypeScript	`npm install @caldera/platformxe-sdk`	`client.whoami`
Python	`pip install platformxe`	`client.whoami`
Go	`go get github.com/calderax/platformxe-go`	`client.Whoami`

Boot-time self-check

The recommended pattern is to call whoami.get() at consumer boot to verify the API key is valid AND the platform is the expected environment.

import { PlatformXeClient } from '@caldera/platformxe-sdk';

const client = new PlatformXeClient({ apiKey: process.env.PLATFORMXE_API_KEY! });

const me = await client.whoami.get();
console.log(`PlatformXe ready as ${me.callerService} (${me.organizationId})`);
console.log(`Scopes: ${me.scopes.join(', ')}`);

// Surface warnings to your boot log so ops notices BEFORE keys break in production
if (me.gracePeriodWarning) console.warn(me.gracePeriodWarning);
if (me.keyExpiryWarning) console.warn(me.keyExpiryWarning);

// Detect env drift — dev consumer accidentally pointed at prod (or vice-versa)
const expectedEnv = process.env.NODE_ENV === 'production' ? 'prod' : 'dev';
if (me.platformxDbEnv !== 'unknown' && me.platformxDbEnv !== expectedEnv) {
  throw new Error(
    `PlatformXe env mismatch: consumer is ${expectedEnv}, platform is ${me.platformxDbEnv} (host: ${me.platformxDbHost})`
  );
}

me = client.whoami.get()
print(f"PlatformXe ready as {me['callerService']} ({me['organizationId']})")

me, err := client.Whoami.Get()
if err != nil { log.Fatal(err) }
fmt.Printf("PlatformXe ready as %s (%s)\n", me.CallerService, me.OrganizationID)

Response fields

Field	Type	Description
`callerService`	`string`	Logical service name attached to the API key.
`organizationId`	`string`	Tenant the key belongs to.
`apiKeyId`	`string`	Stable identifier of the key.
`label`	`string \| null`	Human-friendly label.
`scopes`	`string[]`	Granted scopes (`messaging:send`, `identity:read`, …).
`requestCount`	`number`	Lifetime request count.
`lastUsedAt`	`string \| null`	ISO 8601 timestamp of the most recent successful auth.
`expiresAt`	`string \| null`	ISO 8601 expiry of the key.
`gracePeriodWarning`	`string \| null`	Set when the request was authenticated against the previous key hash AND the grace window is < 6h from expiring.
`keyExpiryWarning`	`string \| null`	Set when the active key is < 7 days from expiring.
`platformxDbHost`	`string \| null`	First segment of the platform's DB host. Never includes credentials.
`platformxDbEnv`	`'dev' \| 'prod' \| 'unknown'`	Best-effort env label.
`platformxNodeEnv`	`string`	`VERCEL_ENV` or `NODE_ENV`.

Scopes required

whoami.get() requires only a valid API key — no specific scope.