Skip to main content
Egma uses two credential types: browser sessions for the web dashboard, and API keys for the CLI, exporters, and direct API access. Both work on the same routes — you do not need a separate login for each. This page covers how to get in, how to get a key, how to use it, and how to manage who else has access.

​
Signing up

Open your Egma instance in a browser — http://localhost:3101 for a default local deployment — and sign up. On a fresh instance the first person to sign up claims it: your account is created, your organization is created, and you become its admin in one step. Open signup closes immediately after — everyone who joins after you arrives by invitation. If the instance requires email verification (configured via EGMA_SMTP_URL), confirm your address before proceeding.

​
Signing in

Navigate to your Egma instance and enter your email and password. Your session is valid for the browser you signed in on. The session cookie is scoped to the instance’s origin, so it is not shared with any other service.

​
Getting an API key

Run egma login in your terminal. The CLI initiates a device code flow: it prints a short code, opens your browser to the approval page with the code pre-filled, and waits. Approve the request in your browser, select which project the terminal is acting for, and the CLI exchanges the code for an API key.
The key is stored at ~/.egma/credentials by default. See Credential storage location to change this with EGMA_HOME.
The CLI’s login command is also the final step of egma (the first-run onboarding command). If you have already run that, you have a key stored and do not need to run login separately.

​
Via the web dashboard

  1. Sign in to your Egma instance.
  2. Navigate to Settings → API Keys.
  3. Click Create.
  4. Copy the key immediately — it is shown in full only once.

​
Via the API

Send a POST request to /api/keys. You must authenticate this request with an existing session cookie or API key.

​
API key format

Every Egma API key begins with the prefix egma_sk_, followed by 32 random bytes. The full key is shown only at creation time. The platform stores a SHA-256 hash of the key alongside the last four characters — enough to identify which key is in use, but never enough to reconstruct it.

​
Using an API key

Pass your API key as a Bearer token in the Authorization header of every request:
The same header format applies to the OpenTelemetry exporter endpoint, the REST API, and any direct curl calls.

​
Key scoping and trace ingestion

A key minted for the whole organization cannot file telemetry spans to the dashboard. Keys are scoped when they are created: a project-scoped key routes incoming spans to that project, where the dashboard can find them. An org-wide key files spans under no project at all, and those spans are invisible in the dashboard.Always mint the key your agent’s exporter uses against a specific project.
The distinction matters in two places:
  • Trace ingestion (POST /v1/traces): use a project-scoped key. Org-wide keys at member or admin role are not refused, but the spans they carry are filed under no project at all — invisible in the dashboard. A key held by a viewer is refused for trace ingestion regardless of scope, because sending spans is a write.
  • Management operations (creating projects, reading members, calling PATCH /api/platform/settings): an org-wide key works fine.

​
Revoking a key

​
Via the dashboard

  1. Navigate to Settings → API Keys.
  2. Find the key you want to revoke.
  3. Click Revoke.
The key stops working on the very next request that presents it.

​
Via the API

Replace :id with the key’s identifier (visible in the key list).
Removing a team member revokes all keys they minted, automatically and immediately. You do not need to revoke their keys separately.

​
Inviting team members

Only admins can invite new members. Open the Members page, type the invitee’s email address, choose a role, and send the invitation. If your instance has no email transport configured (EGMA_SMTP_URL is not set), the invitation link is returned directly to you rather than sent by email. Pass it to your colleague however you like — the link works once and expires after seven days. The invitation is accepted by the address it was sent to only. An expired invitation and an already-accepted one return different messages so you know whether to resend or tell the person they are already in.

​
Roles

Egma has three roles. Every role may create an API key for themselves — the login flow mints one as its last step.
An organization always keeps at least one admin. The last admin cannot be demoted, removed, or deactivated.
Role changes take effect on the next request — there is no grace period. Demoting a member stops their exporters’ ability to ingest spans immediately, with no key touched.

​
Credential storage location

The CLI stores your credentials at ~/.egma/credentials by default. Override this by setting EGMA_HOME:
This is useful in CI environments or when running multiple Egma instances side by side.