> For the complete documentation index, see [llms.txt](https://docs.revenium.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.revenium.io/integrations/api-key-permissions.md).

# API Key Permissions

Revenium API keys use scoped prefixes for metering, write access, and read-only integrations. Choose the narrowest scope your integration needs.

Revenium API keys authenticate SDKs, middleware, OpenTelemetry exporters, CLI tools, MCP servers, and administrative integrations. Each scoped key prefix shows what the key is allowed to do. Use the narrowest key that supports the workflow you are configuring.

## Key Types

Every Revenium scoped API key carries a prefix indicating its permission scope:

| Prefix    | Scope               | Recommended use                                                                                                                                                                        |
| --------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rev_mk_` | Metering            | Production applications, SDK ingestion, middleware, and OpenTelemetry exporters that send metering events. Also used by coding-assistant tooling that reads its own team's guardrails. |
| `rev_sk_` | Write / full-access | MCP servers with write tools, administrative scripts, outcome-reporting workflows, provisioning tools, and integrations that need to create or modify Revenium resources.              |
| `rev_rk_` | Read-only           | Dashboards, reports, audit tools, MCP servers used read-only, and internal automation that only needs to read Revenium data.                                                           |

### What a metering key can do

A metering (`rev_mk_`) key can send metering events, attribute coding-assistant sessions to a ticket for its own team, and read its own team's guardrails and developer-experience policy. That is all the access [Revenium Sidekick](https://docs.revenium.io/track-and-control-costs/analyze-ai-tooling-spend/revenium-sidekick.md) needs to stop a developer's Claude Code session at a budget, so it needs no broader key. It remains limited to its own team: it cannot read other teams' rules, create, change, or delete guardrails, or access any other management API beyond those reads, other than the extra reads the Revenium status line for Claude Code uses.

For that status line, a metering key also reads the team's anonymous medians and one developer's own session figures. The four reads are listed in [What the metering key can read for the status line](https://docs.revenium.io/track-and-control-costs/analyze-ai-tooling-spend/setup-claude-code.md#what-the-metering-key-can-read-for-the-status-line).

## Choosing the Right Scope

Pick the narrowest scope that the integration needs:

* Use a metering (`rev_mk_`) key for SDK, middleware, and OTLP integrations that send usage or telemetry data, and for coding-assistant tooling that reads its own team's rules.
* Use a write/full-access (`rev_sk_`) key for MCP servers that use write tools, account automation, provisioning scripts, and outcome-reporting workflows.
* Use a read-only (`rev_rk_`) key for dashboards, reports, MCP servers used read-only, or audit tooling that should not create or modify resources.

Which key for which job:

| Job                                                                                      | Key       |
| ---------------------------------------------------------------------------------------- | --------- |
| Sending usage: SDKs, middleware, OpenTelemetry, coding assistants                        | `rev_mk_` |
| Reporting job outcomes, importing departments, provisioning, MCP server with write tools | `rev_sk_` |
| Dashboards and analytics API reads, MCP server for read-only use                         | `rev_rk_` |

Sending usage accepts `rev_mk_` or `rev_sk_`, and refuses `rev_rk_` with a 403. Prefer the metering key. Reporting a job outcome needs a write key; a metering or read-only key gets a 403.

When a page gives integration-specific guidance, follow that page's key scope. For example, [OpenTelemetry Integration](https://docs.revenium.io/integrations/otlp-integration.md) uses `rev_mk_`, while [MCP Server](https://docs.revenium.io/integrations/mcp-server.md) uses `rev_sk_` (recommended). A read-only `rev_rk_` key also works for the local MCP server when you only read data; tools that create or change things are refused. The hosted MCP connector uses sign-in instead of a key.

## Read-only access for users

The scopes above govern **API keys**. Read-only access also exists at the **user** level: a **Read-Only** role grants a person view-only access to Revenium — they can see the data their scope allows but cannot create, modify, or delete resources. This is the user-account counterpart to a read-only (`rev_rk_`) key. In this release the Read-Only role is assigned through the API rather than the admin UI. See [Manage Users & Teams](https://docs.revenium.io/account-and-resources/manage-users-and-teams.md#roles) for details.

## Creating and Managing Keys

Keys are managed on the **Integrations > SDK Setup** page in the Revenium UI:

* **Create** — The Create API Key dialog lets you pick the **Permissions** (`METERING`, `READ` or `WRITE`) and name the key before it's issued. `METERING` (a `rev_mk_` key) is the default, `READ` issues a `rev_rk_` key, and `WRITE` issues a `rev_sk_` key. Only admins can create `WRITE` keys.
* **View** — The Revenium API Keys table shows each key's name, its scope, the last four characters of the secret, expiry, creator, and creation date. Only the last four characters of the secret are shown after creation — the full value is displayed only once, when the key is created.
* **Rename** — Click the pencil icon in the Actions column (or the key's name) to rename a key inline. Names are free-form and meant to describe where the key is used (e.g., "Production ingestion — us-east", "Finance dashboard").
* **Delete** — Use the delete icon in the Actions column to revoke a key.

## Key Format

Scoped keys have the shape:

```
{PREFIX}_{TENANT_ID}_{SECRET}
```

Where `PREFIX` is `rev_mk_`, `rev_sk_`, or `rev_rk_`; `TENANT_ID` is your encoded organization identifier; and `SECRET` is the secret key material.

### Legacy `hak_` keys

Older `hak_` keys are still accepted everywhere. Their permission is set on the key (older keys default to full access) and the prefix does not show it. Replace a `hak_` key with a scoped key to make its permission visible.

{% hint style="warning" %}
**Treat API keys as secrets.** Do not commit keys to source control, paste them into chat logs, or share them in screenshots. Full-access keys can modify and delete resources. Metering keys can still generate billable events. A metering key cannot change or delete any setting or record. It does create usage records and session ticket labels, and it can read its team's cost-control rules and the status line's figures: the team's developer-experience settings, the team's anonymous medians, and one developer's own session figures, which include that developer's daily cost. Revoke any key you suspect has been exposed.
{% endhint %}

## Related

* [Connections](https://docs.revenium.io/integrations/integrations.md) — overview of Provider Connections and SDK Integrations.
* [Integration Options for AI Metering](https://docs.revenium.io/integrations/integrations.md) — which SDK to use for which stack.
* [OpenTelemetry Integration](https://docs.revenium.io/integrations/otlp-integration.md) — using Revenium with standard OTEL exporters.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.revenium.io/integrations/api-key-permissions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
