# Authentication

> The two kinds of grovs API credentials: the project key and scoped keys.

Source: https://docs.grovs.io/docs/api-reference/authentication

## Authentication

Each endpoint in this reference names the credential it takes.

| Credential      | Used by                                                                                                                                                                                                                                                                  | Sent as                                 |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| **Project key** | [Links](https://docs.grovs.io/docs/api-reference/links), [Segments](https://docs.grovs.io/docs/api-reference/segments), [In-app messages](https://docs.grovs.io/docs/api-reference/in-app-messages), [Server push](https://docs.grovs.io/docs/api-reference/server-push) | `PROJECT-KEY` and `ENVIRONMENT` headers |
| **Scoped key**  | [Event stream](https://docs.grovs.io/docs/api-reference/event-stream) pull feed, [Audit log](https://docs.grovs.io/docs/api-reference/audit-log) export                                                                                                                  | `Authorization: Bearer <key>`           |

Keep every credential on your server. Never ship one in an app or a web page.

```bash
# Project key
curl https://sdk.sqd.link/api/v1/sdk/metrics_for_project \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production"

# Scoped key
curl https://api.sqd.link/api/v1/projects/123/event_stream \
  -H "Authorization: Bearer est_4c1f…"
```

## Project key

Auth: Project key. See [Authentication](https://docs.grovs.io/docs/api-reference/authentication).

The project key authenticates server-to-server calls on the `sdk.` host. Find it in the dashboard under **Developers** › **API Key**.

One key covers both environments. The `ENVIRONMENT` header picks the project: `production` or `test`. Links, segments, in-app messages and campaigns created in one environment are not visible in the other.

**Headers**

- `PROJECT-KEY` (string, required): Your project key.
- `ENVIRONMENT` (string, required): `production` or `test`.

**Errors**

| Status | Meaning                                                                                                                                       |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | PROJECT-KEY is missing, or ENVIRONMENT is not production or test.                                                                             |
| 403    | The key does not match a project, or enterprise_required: segments, in-app messages and server push need an active paid plan on grovs Cloud. |

> **Warning:** The project key gives full access to links, segments, in-app messages and server push in both environments. To regenerate it, contact <support@grovs.io>.

**Request**

```bash
curl -X GET "https://sdk.sqd.link/api/v1/sdk/metrics_for_project" \
  -H "PROJECT-KEY: $GROVS_PROJECT_KEY" \
  -H "ENVIRONMENT: production"
```

**Response 400 Bad Request**

```json
{
  "error": "Invalid ENVIRONMENT value. Allowed: 'production', 'test'"
}
```

**Response 403 Forbidden**

```json
{
  "error": "Invalid credentials"
}
```

## Scoped keys

Auth: Scoped key. See [Authentication](https://docs.grovs.io/docs/api-reference/authentication).

A scoped key reads one thing and cannot change anything. It is not tied to a user, so it keeps working when the person who created it leaves. An instance admin creates it in the dashboard. The full key is shown once.

| Key                      | Reads                                                                                                                                          | Where to create it                                                              |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **Feed token** `est_…`   | The [event stream pull feed](https://docs.grovs.io/docs/api-reference/event-stream) of one project environment. 120 requests a minute per key. | **Developers** › **Data Export** › **Pull feed tokens** › **Create feed token** |
| **Export token** `aet_…` | The [audit log](https://docs.grovs.io/docs/api-reference/audit-log) of one instance. 60 requests a minute per key.                             | **Settings** › **Audit Logs** › **Export tokens** › **Create token**            |

Send the key as a bearer token. The responses:

- `401` with `{ "error": "Invalid or revoked token" }`: the key is unknown or revoked.
- `403`: the key belongs to another project or instance.
- `503`: you are over the rate limit. Back off and retry.

Neither kind expires. Revoke a key in the same dashboard screen to retire it. Revocation takes effect at once.

**Request**

```bash
curl -X GET "https://api.sqd.link/api/v1/projects/{project_id}/event_stream?limit=500" \
  -H "Authorization: Bearer $GROVS_STREAM_KEY"
```

**Response 401 Unauthorized**

```json
{
  "error": "Invalid or revoked token"
}
```