add whoami endpoint

Author: Social Media Post Design For Product

v3/README.md

@@ -143,6 +143,7 @@ in [Quick start](#quick-start) above.
 | Method | Endpoint | Token cost | Description |
 | --- | --- | --- | --- |
 | `GET` | [`/users`](reference/users.md#list-all-users) | 1 | List all users |
+| `GET` | [`/users/whoami`](reference/users.md#get-current-user) | 1 | Get current user |
 | `GET` | [`/users/{user_id}`](reference/users.md#get-a-user) | 1 | Get a user |
 | `GET` | [`/users/{user_id}/active_state`](reference/users.md#get-user-active-state) 🔒 | 1 | Get user active state |
 | `POST` | [`/users/{user_id}/active_state`](reference/users.md#set-user-active-state) 🔒 | 10 | Set user active state |

v3/guides/getting-started.md

@@ -38,7 +38,30 @@ responses, carry no `meta`):
 { "error": "INVALID API KEY" }
 ```
 
-## 3. Authenticate every request
+## 3. See which account your key belongs to
+
+The `GET /users/whoami` endpoint returns the identity behind your key — your
+user id, email, company user group, and root company. Use it to confirm a key
+maps to the account you expect. It costs **1 token**.
+
+```sh
+curl "https://katapultpro.com/api/v3/users/whoami?api_key=YOUR_API_KEY"
+```
+
+```json
+{
+ "status": "success",
+ "data": {
+ "uid": "-O_userAbc123",
+ "email": "you@example.com",
+ "user_group": "-O_companyXyz",
+ "root_company": "-O_rootCompany"
+ },
+ "meta": { "token_count": 9999, "last_refill_time": 1718450000000 }
+}
+```
+
+## 4. Authenticate every request
 
 Every endpoint takes your key as the `api_key` query parameter. There are no
 headers or tokens to manage — just append `api_key` to the URL. For example, to
@@ -61,7 +84,7 @@ curl "https://katapultpro.com/api/v3/jobs?api_key=YOUR_API_KEY"
 Successful route responses follow the same envelope: a `status` of `success`,
 the payload under `data`, and a `meta` object.
 
-## 4. Read the token `meta` on every response
+## 5. Read the token `meta` on every response
 
 Every response from a route handler — both successes **and** errors — includes a
 `meta` object describing your token-bucket state:

v3/openapi.yaml

@@ -1081,6 +1081,25 @@ paths:
  items: { $ref: '#/components/schemas/UserListItem' }
  default: { $ref: '#/components/responses/Error' }
 
+ /users/whoami:
+ get:
+ tags: [Users]
+ operationId: whoAmI
+ summary: Get current user
+ description: Returns the authenticated caller's own identity — the `uid`, `email`, `user_group` (the caller's active company), and `root_company` tied to the API key. Available to any authenticated caller; no admin required. Useful for confirming which account an API key belongs to.
+ x-token-cost: 1
+ responses:
+ '200':
+ description: The caller's identity.
+ content:
+ application/json:
+ schema:
+ allOf:
+ - $ref: '#/components/schemas/SuccessEnvelope'
+ - properties:
+ data: { $ref: '#/components/schemas/WhoAmI' }
+ default: { $ref: '#/components/responses/Error' }
+
  /users/{user_id}:
  parameters:
  - $ref: '#/components/parameters/UserId'
@@ -1800,6 +1819,14 @@ components:
  - $ref: '#/components/schemas/UserListItem'
  - properties:
  metadata: { type: [object, 'null'], additionalProperties: true }
+ WhoAmI:
+ type: object
+ description: The authenticated caller's own identity, tied to their API key.
+ properties:
+ uid: { type: string, description: The caller's user id. }
+ email: { type: [string, 'null'] }
+ user_group: { type: string, description: The caller's company user group id. }
+ root_company: { type: [string, 'null'], description: The caller's root company id. }
 
  responses:
  Error:

v3/reference/users.md

@@ -9,6 +9,7 @@ record require **company admin**; you can always read your own record.
 | Method | Endpoint | Token cost | Description |
 | --- | --- | --- | --- |
 | `GET` | [`/users`](#list-all-users) | 1 | List all users |
+| `GET` | [`/users/whoami`](#get-current-user) | 1 | Get current user |
 | `GET` | [`/users/{user_id}`](#get-a-user) | 1 | Get a user |
 | `GET` | [`/users/{user_id}/active_state`](#get-user-active-state) 🔒 | 1 | Get user active state |
 | `POST` | [`/users/{user_id}/active_state`](#set-user-active-state) 🔒 | 10 | Set user active state |
@@ -23,6 +24,16 @@ GET https://katapultpro.com/api/v3/users
 
 Lists all users (including external users) in the caller's active company. Requires the caller to be a **company admin**.
 
+### Get current user
+
+```sh
+GET https://katapultpro.com/api/v3/users/whoami
+```
+
+**Token cost:** 1
+
+Returns the authenticated caller's own identity — the `uid`, `email`, `user_group` (the caller's active company), and `root_company` tied to the API key. Available to any authenticated caller; no admin required. Useful for confirming which account an API key belongs to.
+
 ### Get a user
 
 ```sh