# Get the caller

Source: https://docs.coderhelm.com/api/reference/account/get-me

`GET /api/me`

Returns who the request is authenticated as. With an API key this is the key itself: its name, who made it, when it expires, its rate limit, and in `capabilities` the scopes it holds right now (cut down to what its maker holds). Call it first to check a key works.

## Authentication

A team API key: `Authorization: Bearer chk_...`. Any key works. See [Authentication](https://docs.coderhelm.com/api/authentication).

## Responses

### 200

The caller.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `api_key` | MeApiKey or null | no | The API key a request was made with. |
| `api_key.created_by` | string | yes | Who made it. The key acts within that person's access. |
| `api_key.expires_at` | string or null | no | When it stops working (RFC 3339), or null if it doesn't expire. |
| `api_key.id` | string | yes | The key's id, the part after `chk_` and before the next `_`. |
| `api_key.name` | string | yes | The name the admin gave it. |
| `api_key.rate_limit_per_minute` | integer | yes | Requests the key may make in a minute. |
| `auth_provider` | string | yes | How the caller signed in: `email`, `google`, `github`, or `api_key`. |
| `avatar_url` | string or null | no | The person's picture. Always null for an API key. |
| `capabilities` | array of string or null | no | The capability keys held. For an API key, its scopes as they stand on this request: never more than its maker holds now. |
| `custom_role` | CustomRoleRef or null | no | A custom role, by id and name. |
| `custom_role.id` | string | yes | The role's id. |
| `custom_role.name` | string | yes | The role's name, as the team page shows it. |
| `email` | string | yes | The person's email. For an API key, its maker's. |
| `github_login` | string or null | no | The person's GitHub login. For an API key, its maker's. |
| `mfa_enabled` | boolean | yes | Whether the person turned on two-factor sign-in. |
| `platform_admin` | boolean | yes | Whether the caller administers the whole CoderHelm install (its operators, set in the install's configuration). Always false for an API key. |
| `role` | string | yes | The built-in role requests run as: `viewer`, `member`, `admin` or `owner`. For a custom role or an API key, the highest built-in role whose capabilities are all held; `capabilities` says exactly what is. |
| `status` | string | yes | The team's account status: `active` or `suspended`. |
| `team_id` | string | yes | The team every request acts on. |
| `user_id` | string | yes | The caller's id: `USER#...` for a person, `APIKEY#<id>` for an API key. |

Headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`.

### 401

The key is missing, malformed, revoked or expired, or the person who made it left the team.

### 403

The key lacks the scope this endpoint needs (`missing_scope`).

### 429

Over the key's rate limit (`rate_limited`), or, for endpoints that start work, over the team's monthly token limit (`token_limit_reached`).

Headers: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `Retry-After`.

### 500

Something failed on CoderHelm's side. Safe to retry reads.

## Example request

cURL:

```bash
curl -X GET 'https://api.coderhelm.com/api/me' \
  -H "Authorization: Bearer $CODERHELM_API_KEY"
```

TypeScript:

```ts
const res = await fetch("https://api.coderhelm.com/api/me", {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.CODERHELM_API_KEY}`,
  },
});
if (!res.ok) {
  const { error, code } = await res.json();
  throw new Error(`${res.status} ${code}: ${error}`);
}
const data = await res.json();
```

Python:

```python
import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['CODERHELM_API_KEY']}",
}
res = requests.request("GET", "https://api.coderhelm.com/api/me", headers=headers)
if not res.ok:
    raise RuntimeError(f"{res.status_code}: {res.json().get('error')}")
data = res.json()
```

## Example response

```json
{
  "api_key": {
    "created_by": "dev@example.com",
    "expires_at": "2027-01-01T00:00:00Z",
    "id": "01jb8x6f4m2c9qz3t7v5w1k0ha",
    "name": "Deploy pipeline",
    "rate_limit_per_minute": 600
  },
  "auth_provider": "api_key",
  "avatar_url": "https://avatars.githubusercontent.com/u/583231",
  "capabilities": [
    "view",
    "runs"
  ],
  "custom_role": {
    "id": "01JB7Z2R4T6V8X0Z2B4D6F8H0K",
    "name": "Release manager"
  },
  "email": "dev@example.com",
  "github_login": "octocat",
  "mfa_enabled": false,
  "platform_admin": false,
  "role": "viewer",
  "status": "active",
  "team_id": "TEAM#4817263",
  "user_id": "APIKEY#01jb8x6f4m2c9qz3t7v5w1k0ha"
}
```