---
title: "Resolve the calling company identity"
method: GET
path: "/v1/whoami"
tags: ["Whoami"]
---

# Resolve the calling company identity

`GET /v1/whoami`

## Request

- Base URL: `https://api.finalpos.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.finalpos.com/v1/whoami`
- Auth: API key in header `x-api-key`

Returns the company identity and key status resolved from the `x-api-key`. Intended as a login gate for internal tooling: pass a company private API key (`sk_...`) and confirm which company, currency, and key it maps to. Read-only. The key must be a company key — an organization key (`x-org-api-key`) is rejected.

## Response `200`

The company identity and key status for the authenticated API key.

- WhoamiResponseDto
  - `companyId` string, required: The company the API key belongs to (MongoDB ObjectId).
  - `companyName` string, required: Display name of the company.
  - `currency` string, required: The company’s configured ISO 4217 currency code. Always present on a 200 response.
  - `country` string: The company’s country (ISO 3166-1 alpha-2) from its address, when set.
  - `key` WhoamiKeyDto, required
    - `permissions` ApiKeyPermissionsDto, required
      - `create` boolean, required: Whether the key may create resources.
      - `read` boolean, required: Whether the key may read resources.
      - `update` boolean, required: Whether the key may update resources.
      - `delete` boolean, required: Whether the key may delete resources.
    - `granularPermissions` object: Per-entity permission additions for granular keys, keyed by entity name (e.g. `product`). Each value lists the extra CRUD actions granted on that entity beyond `permissions`. Absent for general keys.
    - `name` string: Human-readable name of the API key, if one was set when the key was issued.
    - `expiresAt` string, required: Key expiry. The literal `never_expires` when the key has no expiration, otherwise an ISO 8601 date-time string.

## Other responses

- `401`: Missing, invalid, or expired API key, or a non-company key.
- `404`: No company exists for the company id embedded in the API key.
- `422`: The company has no currency configured, so its identity cannot be resolved.
- `429`: Rate limit exceeded. Back off and retry after the `retry-after` header.

---

[API](https://skmtc.dev/finalpos/apis/final-pos-public-api.md) · [All operations](https://skmtc.dev/finalpos/apis/final-pos-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/finalpos/apis/final-pos-public-api/revisions/6a6842dcb479?raw)