---
title: "Check a key"
description: "GET /health"
canonical: "https://docs.nimbusmint.bot/api/operations/gethealth/"
---
> Index: https://docs.nimbusmint.bot/llms.txt

# Check a key

`GET https://api.nimbusmint.bot/partner/v1/health`

Returns the calling key's own metadata. Needs a valid key from an allowed address and no scope; use it to test your setup and to watch the expiry date.

## Authentication

- `privateKey`: `Authorization: Bearer nmk_live_<id>_<secret>`: `<id>` is 12 characters (the key id shown to you is `nmk_<id>`), `<secret>` 64 hex characters. The full token is shown once, when the key is issued; we store only a hash of it and cannot show it again. The key works only from the addresses on its IP allowlist (public IPv4 /24 or narrower, IPv6 /48 or narrower, at most 16 entries). It expires on its `expires_at` (at most one year after issue), and a revoked key stops working within 10 seconds. Keep it on your servers; never put it in a client.

## Responses

### 200

The key works from this address.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `tenant` | string | yes |  |
| `key_id` | string | yes |  |
| `scopes` | string[] | yes |  |
| `expires_at` | string (date-time) | yes |  |

Example `health`:

```json
{
  "tenant": "example-partner",
  "key_id": "nmk_abcdefgh2345",
  "scopes": [
    "read:hits"
  ],
  "expires_at": "2027-10-01T00:00:00Z"
}
```

### 401

The key is missing, malformed, unknown, expired or revoked, or its partner is disabled. Always `invalid_key`.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | One of: `invalid_key`, `ip_not_allowed`, `scope_missing`, `rate_limited`, `ip_trust_unconfigured`, `tenant_api_disabled`, `invalid_request`, `window_too_large`, `not_found`, `internal`. |
| `message` | string | yes |  |

Example `invalid`:

```json
{
  "code": "invalid_key",
  "message": "missing, invalid, expired or revoked key"
}
```

### 403

The calling address is not on the key's allowlist (`ip_not_allowed`), or the key lacks the route's scope (`scope_missing`).

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | One of: `invalid_key`, `ip_not_allowed`, `scope_missing`, `rate_limited`, `ip_trust_unconfigured`, `tenant_api_disabled`, `invalid_request`, `window_too_large`, `not_found`, `internal`. |
| `message` | string | yes |  |

Example `ip`:

```json
{
  "code": "ip_not_allowed",
  "message": "this address may not use this key"
}
```

### 429

The key's rate limit, or the API's overall limit, is exceeded (`rate_limited`).

Headers:

- `Retry-After`: Seconds to wait before retrying.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | One of: `invalid_key`, `ip_not_allowed`, `scope_missing`, `rate_limited`, `ip_trust_unconfigured`, `tenant_api_disabled`, `invalid_request`, `window_too_large`, `not_found`, `internal`. |
| `message` | string | yes |  |

Example `limited`:

```json
{
  "code": "rate_limited",
  "message": "rate limit exceeded"
}
```

### 503

The API is switched off (`tenant_api_disabled`), not configured (`ip_trust_unconfigured`) or temporarily unable to answer (`internal`). Retry later; `Retry-After` is sent when a retry is expected to succeed soon.

Headers:

- `Retry-After`: Seconds to wait before retrying.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | yes | One of: `invalid_key`, `ip_not_allowed`, `scope_missing`, `rate_limited`, `ip_trust_unconfigured`, `tenant_api_disabled`, `invalid_request`, `window_too_large`, `not_found`, `internal`. |
| `message` | string | yes |  |

Example `disabled`:

```json
{
  "code": "tenant_api_disabled",
  "message": "the partner API is disabled"
}
```

## Errors

| Status | `code` | Meaning |
| --- | --- | --- |
| 401 | `invalid_key` | The key is missing, malformed, unknown, expired or revoked, or its partner is disabled. Always `invalid_key`. |
| 403 | `ip_not_allowed` | The calling address is not on the key's allowlist (`ip_not_allowed`), or the key lacks the route's scope (`scope_missing`). |
| 403 | `scope_missing` | The calling address is not on the key's allowlist (`ip_not_allowed`), or the key lacks the route's scope (`scope_missing`). |
| 429 | `rate_limited` | The key's rate limit, or the API's overall limit, is exceeded (`rate_limited`). |
| 503 | `tenant_api_disabled` | The API is switched off (`tenant_api_disabled`), not configured (`ip_trust_unconfigured`) or temporarily unable to answer (`internal`). Retry later; `Retry-After` is sent when a retry is expected to succeed soon. |
| 503 | `ip_trust_unconfigured` | The API is switched off (`tenant_api_disabled`), not configured (`ip_trust_unconfigured`) or temporarily unable to answer (`internal`). Retry later; `Retry-After` is sent when a retry is expected to succeed soon. |
| 503 | `internal` | The API is switched off (`tenant_api_disabled`), not configured (`ip_trust_unconfigured`) or temporarily unable to answer (`internal`). Retry later; `Retry-After` is sent when a retry is expected to succeed soon. |

What to do about each: [Errors](https://docs.nimbusmint.bot/errors.md).

## Example request

### curl

```sh
curl "https://api.nimbusmint.bot/partner/v1/health" \
  -H "Authorization: Bearer $NIMBUS_PRIVATE_KEY"
```

### Node

```js
// Node 18+ (built-in fetch). Keep the key on your server.
const url = new URL('https://api.nimbusmint.bot/partner/v1/health');
const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.NIMBUS_PRIVATE_KEY}` },
});
console.log(res.status, await res.json());
```

### Python

```python
import os
import requests

res = requests.get(
    "https://api.nimbusmint.bot/partner/v1/health",
    headers={"Authorization": f"Bearer {os.environ['NIMBUS_PRIVATE_KEY']}"},
    timeout=10,
)
print(res.status_code, res.json())
```