---
title: "Auth API"
description: "Use when you check that an API key works and read the account, plan, library size and monthly read usage behind it with GET /auth/whoami."
url: https://docs.heytrove.ai/reference/api/auth
updated: 2026-10-01
---

# Auth API

> Load this page when: you need to verify an API key or read the account's plan and read usage over HTTP

## For agents

- Call GET /auth/whoami to check a key and read plan, itemCount and monthlyReadsUsed.
- A null monthlyReadLimit means unlimited.

One endpoint tells you who a key belongs to and where the account stands against its limits.

## Get the current account

`GET https://heytrove.ai/api/v1/auth/whoami`

Returns the account behind the key. It takes no parameters.

**Request**

```bash
curl https://heytrove.ai/api/v1/auth/whoami \
  -H "Authorization: Bearer trove_your_key"
```

**Response**

```json
{
  "id": "user_id_here",
  "email": "you@example.com",
  "name": "Ada Example",
  "emailKind": "personal",
  "emailDomain": "example.com",
  "tier": "FREE",
  "tierDisplay": "Personal",
  "pricingCohort": "v2",
  "itemLimit": 12,
  "itemCount": 3,
  "ownedCount": 2,
  "subscribedCount": 1,
  "monthlyReadLimit": 30,
  "monthlyReadsUsed": 7,
  "readLimitMessage": null,
  "canPublishToMarketplace": false,
  "trial": null
}
```

`emailKind` is `"personal"` or `"work"`, based on the address. `emailDomain` is the lower-cased domain of the address, or `null` when there is none.

The numbers are an example. Your plan sets them. `monthlyReadLimit` is `null` when reads are unlimited. `readLimitMessage` holds a sentence you can show the user once the monthly limit is reached, and is `null` before that.

**Errors**

| Status | Message | Fix |
| --- | --- | --- |
| 401 | `Invalid or revoked API key` | Create a new key. See [Errors](https://docs.heytrove.ai/reference/api.md#errors). |

**CLI equivalent**: [trove auth whoami](https://docs.heytrove.ai/reference/cli/auth.md#trove-auth-whoami).