---
description: Separate trace data into projects and manage the API keys that send it.
---

# Projects and API keys

Projects separate applications, environments, or workloads in WeaveScope.
Every API key belongs to one project, and every trace sent with that key lands
in the same project.

## Manage projects

Open **Settings → Projects** to create, rename, switch, or delete projects.

The project list shows:

| Field | Meaning |
| --- | --- |
| Project | The project's display name. |
| Public ID | Its stable `proj_...` identifier. |
| Retained traces | Trace records still inside the retention window. |
| Retention | How long the project keeps trace data. |
| Created | When the project was created. |

Deleting a project permanently removes its API keys, traces, and stored
payloads. Usage already counted during the current billing cycle is not reset.
You cannot delete the organization's last project.

## Project limits

| Plan | Projects |
| --- | ---: |
| Free | 1 |
| Pro | Unlimited |
| Scale | Unlimited |
| Enterprise | Custom |

An immediate plan change is blocked if the organization already has more
projects than the target plan allows. See [Limits and billing](limits-billing.md)
for scheduled downgrade behavior.

## Manage API keys

Open **Settings → API keys** after selecting the project you want to connect.

API keys:

- Begin with `ws_`.
- Are shown in full only once, immediately after creation.
- Send data to one project.
- Can be revoked at any time.
- Show when they were last used.

If you lose the full token, revoke it and create a replacement.

{% hint style="warning" %}
Treat every `ws_...` key as a production secret. Anyone with the key can send
trace data to its project.
{% endhint %}

## Configure BeamWeaver

Store the key as `WEAVESCOPE_API_KEY` and configure the hosted endpoint:

```elixir
config :beam_weaver,
  weave_scope: [
    endpoint: "https://app.weavescope.com",
    api_key: System.fetch_env!("WEAVESCOPE_API_KEY")
  ]
```

Use separate projects and API keys when you want to isolate production,
staging, and development traces.

## Authenticate direct ingestion

Send the project API key in either header:

{% tabs %}
{% tab title="Bearer token" %}
```http
Authorization: Bearer ws_...
```
{% endtab %}

{% tab title="x-api-key" %}
```http
x-api-key: ws_...
```
{% endtab %}
{% endtabs %}

BeamWeaver uses the Bearer token header.

Custom clients and OpenTelemetry exporters can send data directly with the
same project key. For example:

```bash
curl https://app.weavescope.com/api/v1/observations/batch \
  -H "authorization: Bearer $WEAVESCOPE_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "events": [
      {
        "observation_id": "manual-root-1",
        "trace_id": "manual-root-1",
        "operation": "finish",
        "name": "manual.test",
        "kind": "span",
        "status": "success"
      }
    ]
  }'
```

See the [Ingestion API](ingestion.md) for the complete request and response
contract.

## Key permissions

Project ingestion keys include `ingest:write` and `traces:read`. A valid key
without `ingest:write` receives `403 Forbidden` when it tries to ingest data.

## Rotate a key

1. Create a replacement key in the same project.
2. Deploy the new secret.
3. Confirm that the replacement key shows recent use.
4. Revoke the old key.

Rotating a key affects only its project.