Capabilities

Meta

Identity and introspection endpoints. One capability today — meta.whoami — designed to be dirt cheap and side-effect-free so you can use it as an SDK bootstrap check or a rate-limited health probe.

meta.whoami

GET/api/v2/me

Identity and capabilities of the calling credential. Requires no scopes — any valid key or OAuth token works.

scope: (none)cost: 1idempotent

Request

bash
curl -sS https://api.alloovium.com/api/v2/me \
  -H "Authorization: Bearer $ALLOOVIUM_API_KEY"

No body and no query parameters. The API derives everything from the header header — pass either an API key (live / test) or an OAuth bearer JWT.

Response (API key)

json
{
  "user_id": "1f02d9ef-...",
  "tenant_id": "c7a1e9c2-...",
  "auth_method": "api_key",
  "email": "alex@example.com",
  "api_key_id": "2e5f09bb-...",
  "api_key_name": "Backend worker — production",
  "api_key_prefix": "ak_live_AB7K",
  "environment": "live",
  "rate_limit_tier": "pro",
  "scopes": [
    "chat:read",
    "chat:write",
    "templates:read",
    "templates:write",
    "vault:read",
    "vault:write",
    "workflows:read",
    "workflows:write"
  ]
}

Response (OAuth)

json
{
  "user_id": "1f02d9ef-...",
  "tenant_id": "c7a1e9c2-...",
  "auth_method": "oauth",
  "client_id": "client_9a8b7c6d",
  "scopes": [
    "chat:read",
    "vault:read"
  ]
}

OAuth principals do not surface an email, API key name, environment, or rate-limit tier. If you need those, use an API key instead.

Fields

Field	Always present?	Notes
user_id	yes	UUID of the Alloovium user behind the credential.
tenant_id	yes	UUID of the tenant the user belongs to.
auth_method	yes	'api_key' or 'oauth'.
scopes	yes	Sorted list of capability scopes granted to the credential.
email	api_key only	User's email address (may be null if unset).
api_key_id	api_key only	UUID of the specific key resolving the request.
api_key_name	api_key only	Human-readable label the user gave the key.
api_key_prefix	api_key only	First ~12 chars of the raw key, e.g. 'ak_live_AB7K'.
environment	api_key only	'live' or 'test'.
rate_limit_tier	api_key only	free / standard / pro / enterprise.
client_id	oauth only	OAuth client_id that minted the bearer token.

Use this for SDK initialization

Call capability when your SDK boots. If it succeeds, you have a working credential; the scopes array tells you which capabilities you can call; and tier tells you what bucket the key is in. Because the handler makes no database calls, this endpoint is sub-millisecond on the server.

Do not use as a liveness probe loop