# Get the connected account

Source: https://docs.rocketverifier.com/api/account
Endpoint: `GET https://api.rocketverifier.com/v1/me` (OAuth scope `account:read`)

> GET /v1/me returns the account the current credential acts for, whether it bills a personal or an organization account, the available credits and the scopes. OAuth access tokens also get the connected app and its monthly credit cap, and need the account:read scope. API keys can always call it, and it works at a zero balance.

cURL:

```bash
curl https://api.rocketverifier.com/v1/me \
  -H "Authorization: Bearer $ROCKETVERIFIER_ACCESS_TOKEN"
```

Node.js:

```js
import RocketVerifier from "@rocketverifier/sdk";

const rv = new RocketVerifier({ accessToken: process.env.ROCKETVERIFIER_ACCESS_TOKEN });
const me = await rv.getMe();
console.log(`Connected as ${me.email}, ${me.credits.toLocaleString()} credits`);
```

Python:

```python
import os
from rocketverifier import RocketVerifier

rv = RocketVerifier(access_token=os.environ["ROCKETVERIFIER_ACCESS_TOKEN"])
me = rv.get_me()
print(f"Connected as {me.email}, {me.credits:,} credits")
```

Response 200:

```json
{
  "email": "jane@acme.com",
  "name": "Jane Doe",
  "account_type": "organization",
  "organization": { "id": "org_8f2a", "name": "Acme Inc" },
  "credits": 12400,
  "auth_type": "oauth",
  "scopes": ["verify:single", "verify:bulk", "jobs:read", "account:read"],
  "app": {
    "client_id": "rvapp_3kq9x2",
    "name": "Pengo",
    "monthly_credit_limit": 5000,
    "credits_used_this_month": 320
  }
}
```

Apps built on [RocketVerifier Connect](https://docs.rocketverifier.com/oauth/scopes) use this endpoint to show "Connected as jane@acme.com, 12,400 credits" right after the user approves them. With an API key, it is a quick way to check which account and scopes a key carries.

## Request

Send the credential in the `Authorization` header. There are no parameters.

- **OAuth access tokens** (`rv_at_`) need the `account:read` scope. Without it, the call returns `403 insufficient_scope`.
- **API keys** can always call it, whatever their scopes.
- **Balance:** works at a zero balance and costs nothing.

## Response

| Field | Type | Description |
| --- | --- | --- |
| `email` | string or null | Email of the user the credential acts for (the owner, for organization keys). |
| `name` | string or null | The user's name. Set for OAuth tokens. |
| `account_type` | enum | `organization` for organization API keys and for OAuth tokens that bill an organization. required; one of `personal`, `organization` |
| `organization` | object or null | Set when the credential bills an organization. |
| `organization.id` | string |  |
| `organization.name` | string or null | Set for OAuth tokens. |
| `credits` | integer | Credits available to this credential now. required |
| `auth_type` | enum | required; one of `api_key`, `oauth` |
| `scopes` | array of strings | The scopes this credential carries. required |
| `app` | object or null | The OAuth app the token was issued to. Null for API keys. |
| `app.client_id` | string |  |
| `app.name` | string |  |
| `app.monthly_credit_limit` | integer or null | Monthly credit cap the user set for this app. Null when uncapped. |
| `app.credits_used_this_month` | integer | Credits this app used this month. |

## Read the response by credential

The same fields describe four kinds of credential.

| Credential | `auth_type` | `account_type` | `organization` | `app` |
| --- | --- | --- | --- | --- |
| Personal API key | `api_key` | `personal` | `null` | `null` |
| Organization API key | `api_key` | `organization` | `{ "id": ... }` | `null` |
| OAuth token for a personal account | `oauth` | `personal` | `null` | The connected app |
| OAuth token that bills an organization | `oauth` | `organization` | `{ "id", "name" }` | The connected app |

- **`email`** is the user the credential acts for. Organization keys act as the organization's owner.
- **`credits`** is the balance available to this credential, the same number as [`GET /v1/credits`](https://docs.rocketverifier.com/api/credits). On an organization with credit pooling, it is the larger of the pool and the billed user's own balance.
- **`scopes`** lists what the credential can call. Check it before you show features that need a scope the user did not approve.
- **`app.monthly_credit_limit`** is the monthly cap the user set for your app, and `app.credits_used_this_month` is what your app used against it. A charge past the cap returns `402 api_key_spend_cap_reached`.

## Errors

| Status | `error.code` | When it happens |
| --- | --- | --- |
| 401 | `unauthorized` | No credential, or an invalid or revoked API key. |
| 401 | `api_key_expired` | The API key passed its expiry date. |
| 401 | `invalid_token` | The OAuth access token expired or was revoked. Refresh it and retry once. |
| 403 | `insufficient_scope` | The OAuth token lacks `account:read`. |
| 403 | `ip_not_allowed` | The key or organization has an IP allowlist that does not include the caller. |
| 403 | `account_suspended` | The account is suspended. |
| 429 | `rate_limited` | Too many requests. Wait for the `Retry-After` seconds. |

Every error uses the [standard error shape](https://docs.rocketverifier.com/api#handle-errors). The [authentication guide](https://docs.rocketverifier.com/authentication) covers keys and tokens in depth.

## Frequently asked questions

### Does an API key need the account:read scope?

No. API keys can always call GET /v1/me. Only OAuth access tokens need account:read.

### What is the difference between /v1/me and /v1/credits?

Both return the same available balance. /v1/me adds who the credential acts for and its scopes, and /v1/credits adds today's and this month's usage.

### Which email does an organization API key return?

The email of the organization's owner, because organization keys act and are billed as the owner. account_type is organization and organization.id names the organization.
