Concepts

Authentication

Every request carries one credential in one header: Authorization: Bearer <credential>. The gateway verifies it with One account on each request, then forwards the verified organization, principal and scopes to the service.

Which credential to use

Send exactly one Authorization header. A request with none, or with more than one, answers 401 BEARER_REQUIRED. An invalid, expired or revoked credential answers 401 CREDENTIAL_INVALID.

Organization API keys

An API key belongs to one organization and carries a fixed set of scopes. It acts as itself, not as the person who created it.

Create a key

API keys → Create
  Name      ci-deploy
  Scopes    hives:read, hives:write   (write includes read)
  Expiry    choose a date, or none
→ The secret is shown once. Copy it now.

genesis login
genesis keys create ci-deploy --scopes hives:read,hives:write --expires 2027-01-01T00:00:00Z

# The raw key is never shown to anyone; agents use it through Blinds delegation.
genesis keys create ci-deploy --scopes hives:read,hives:write --blinds

• Only organization owners and admins can create, rotate and revoke keys, and a key can carry only scopes your role holds.
• Creating, listing and revoking keys needs a signed-in person. An API key cannot mint another key.
• A key with no scopes can call nothing, so one is never created.

Use a key

curl "https://os.one.ml/api/v1/whoami" -H "Authorization: Bearer $GENESIS_API_KEY"

import { Genesis } from '@lifesi/genesis'
const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })

GENESIS_API_KEY=sk_... genesis hives projects list

{ "env": { "GENESIS_API_KEY": "sk_..." } }

The SDK, CLI and MCP server read GENESIS_API_KEY when no key is passed. A key in the environment takes precedence over a saved genesis login.

Rotate and revoke

• Revoke in the Console (API keys → the key → Revoke) or with genesis keys revoke <key_id>. Anything using the key stops working within about a minute. A revoked key cannot be restored.
• Rotate where the Console offers it: the key keeps its name, scopes and expiry, the current secret stops working at once, and the new secret is shown once.
• The Console lists each key's scopes, expiry and last use; genesis keys list lists your organization's keys. Neither shows a secret again.

Keep keys safe

• Store keys in a secret manager or your CI's secret store, never in source control.
• Give each workload its own key with only the scopes it needs, so you can revoke one without touching the others.
• Set an expiry on keys for people and short-lived jobs.
• Prefer --blinds for agents: the key is held in Blinds custody and delegated, and nobody sees the raw value.

Signing in with One

People sign in with their One account. The CLI keeps the session in your operating system's keychain.

genesis login            # opens your browser
genesis login --device   # prints a code to approve from any signed-in browser
genesis whoami
genesis logout

A signed-in session acts as you, in the organization and selection you chose (genesis orgs switch, genesis context select). Operations that act for a person, such as creating API keys or approving consent in Blinds, need a session; the API reference marks them Signed-in session.

How the gateway verifies a request

1. It reads the single Authorization: Bearer header.
2. It verifies the credential with One account (POST /v4/iam/credentials/verify) and gets its organization, principal, kind and scopes.
3. It checks the operation's required scope.
4. It forwards the request to the service with a signed identity: organization, principal, scopes, method, path and time.

GET https://os.one.ml/api/v1/whoami returns what step 2 produced for your credential.

Related

• Scopes — every scope and what it allows.
• Access and sign-in — roles and sign-in for teams.

One Superintelligence, Inc. · Built from Genesis 0.1.12 and the live gateway on 2026-10-20. Support