Skip to content

authentication.md

Latest commit

 

History

History
169 lines (121 loc) · 10.2 KB

authentication.md

File metadata and controls

169 lines (121 loc) · 10.2 KB
Raw

🔐 Authentication

All Molecule APIs require authentication. This page covers how to obtain credentials, which headers each API expects, and the specific authentication model for the Labs API.

Obtaining API Access

All Molecule APIs require authentication with an API key. To request access:

  1. Join our Discord community
  2. Contact the Molecule team with your use case
  3. You'll receive:
    • API Key - Required for all APIs
    • Service Token - Additional token for Labs API (if needed)

Authentication Headers

API Required Headers Example
Labs API (queries) x-api-key x-api-key: YOUR_API_KEY
Labs API (mutations, service token)

x-api-key
X-Service-Token

x-api-key: YOUR_API_KEY
X-Service-Token: YOUR_SERVICE_TOKEN
Labs API (mutations, Privy user)

x-api-key
Authorization
x-wallet-address

x-api-key: YOUR_API_KEY
Authorization: Bearer PRIVY_TOKEN
x-wallet-address: 0x…
Tokenization API x-api-key x-api-key: YOUR_API_KEY
IPNFT API (Deprecated) x-api-key x-api-key: YOUR_API_KEY

Labs API Authentication

The Labs API has different authentication requirements depending on the operation type:

Rule of thumb: Most queries are public (API Key only). Write mutations are authenticated, and most accept either a Service Token or a Privy user session — pick whichever fits your caller. The exceptions are called out below: one query is gated, the two Service Token lifecycle mutations are service-token-only, and generateServiceToken bootstraps a token with a Privy session or wallet signature.

Summary of the model:

  • Most queries are public: API Key only for read operations. Exception: legalAgreementTemplate requires a Service Token or an authenticated session.
  • Write mutations are authenticated, with two interchangeable paths: API Key plus either X-Service-Token (machine callers — services, bots, agents) or Authorization + x-wallet-address (Privy user session — browser and app callers). Authorization is then evaluated against the caller's identity either way.
  • Exceptions: extendServiceToken and revokeServiceToken accept only a Service Token. generateServiceToken accepts only a Privy session or wallet signature, since it mints the token in the first place.
  • Service Token: Identifies which specific lab/dataroom you have write access to.
  • File-level access control is handled via Molecule's Onchain-Verified Envelope Encryption, not query authentication — see Data Privacy & Access.

Public Queries (Read-Only)

These queries are public and only require an API Key:

  • labs - List all labs with pagination
  • labWithDataRoomAndFiles - Get lab details and files
  • labActivity - Get activity feed for a lab, (available filters: ANNOUNCEMENT | FILE)
  • activities - Get global activity feed, (available filters: ANNOUNCEMENT | FILE)
  • dataRoomFile - Get file by path
  • searchLabs - Search across labs, files, and announcements
  • fileCategoriesAndTags - List valid file categories and their tags
  • getServiceSignInMessage - Get the message a service signs to obtain a token
  • getDidLinkStatus - Get background DID-linking status for a lab
  • legalAgreementStatus - Check whether a lab's legal agreement is signed
  • onChainActivity - Onchain event feed for a lab or wallet
  • listLabMembers - List a lab's members
x-api-key: YOUR_API_KEY

Authenticated query — API Key plus a Service Token, or an authenticated user session:

  • legalAgreementTemplate - Get the populated agreement to sign (the signer's authenticated session, or a service token)

Protected Mutations (Write Operations)

All write mutations require an API Key plus proof of caller identity. For most mutations there are two interchangeable ways to prove identity — the resolver accepts a Service Token if one is present, and otherwise falls back to authenticating the Privy user:

Option 1 — Service Token (services, bots, agents, CI/CD):

x-api-key: YOUR_API_KEY
X-Service-Token: YOUR_SERVICE_TOKEN

Option 2 — Privy user session (browser and app callers acting as a signed-in user):

x-api-key: YOUR_API_KEY
Authorization: Bearer YOUR_PRIVY_TOKEN
x-wallet-address: YOUR_WALLET_ADDRESS

Either way, the caller still has to be authorized for the target lab — a Service Token carries its own lab scope, and a Privy session is checked against the wallet's onchain role (LabNFT owner, authorized multisig signer, or an active role on AccessResolver). Supplying neither returns a NO_AUTH error naming both paths.

Mutations accepting either path:

  • createLab - Create a lab (data room) for an onchain lab (OCL) · 💳 also available pay-per-call via x402 Gateway
  • initiateCreateOrUpdateFile - Initiate file upload · 💳 also available pay-per-call via x402 Gateway
  • finishCreateOrUpdateFile - Complete file upload · 💳 also available pay-per-call via x402 Gateway
  • updateFileMetadata - Update file metadata
  • deleteDataRoomFile - Delete a file
  • createAnnouncement - Create an announcement · 💳 also available pay-per-call via x402 Gateway
  • updateLabNftMetadata - Update LabNFT display metadata (OCL admin only)
  • generateLabImageUploadUrl - Get a presigned URL to upload a LabNFT image (OCL admin only)
  • signLegalAgreement - Record acceptance of a legal agreement
  • generateDataEncryptionKey - Generate a standalone data encryption key · 💳 also available pay-per-call via x402 Gateway
  • decryptDataKey - Decrypt a file's data key for an authorized caller · 💳 also available pay-per-call via x402 Gateway

Service-Token-only mutations — these manage token lifecycle and reject Privy sessions:

  • extendServiceToken - Extend service token expiration
  • revokeServiceToken - Revoke a service token
x-api-key: YOUR_API_KEY
X-Service-Token: YOUR_SERVICE_TOKEN

generateServiceToken is the bootstrap exception, in the opposite direction: it mints a Service Token, so it accepts only an API Key plus either a Privy session or a wallet signature — not a pre-existing Service Token. See Obtaining Tokens.

Pay-per-call alternative. Mutations tagged 💳 above can also be called through the x402 Gateway, which settles a USDC payment on Base per request and mints a short-lived service token on the fly — no long-lived credentials required. Useful for autonomous AI agents and third-party tools that pay for users.

Obtaining API Key and Service Token

To obtain access credentials:

  1. Join our Discord community
  2. Contact the Molecule team and provide:
    • Your wallet address (will be linked to the service token)
    • Intended use case / service name
    • Which lab/dataroom you need access to
    • Desired token expiration period
  3. The team will generate and provide you with:
    • API Key - Used for all Molecule APIs
    • Service Token (JWT string) - Grants access to specific lab
    • Token ID - For management operations

Using Your Credentials

For all queries (read-only operations):

x-api-key: YOUR_API_KEY

For mutations (write operations) — as a service:

x-api-key: YOUR_API_KEY
X-Service-Token: YOUR_SERVICE_TOKEN

For mutations — as a signed-in user (accepted by all mutations except extendServiceToken and revokeServiceToken):

x-api-key: YOUR_API_KEY
Authorization: Bearer YOUR_PRIVY_TOKEN
x-wallet-address: YOUR_WALLET_ADDRESS

Why more than one header for mutations?

  • API Key: Authenticates you as a valid Molecule API user
  • Service Token: Identifies which specific lab/dataroom your service has write access to
  • Privy token + wallet address: Identifies the human caller instead, whose write access is derived from their wallet's onchain role

Which path to choose: use a Service Token for unattended callers (backends, bots, agents, CI/CD) where there is no user session to draw on. Use the Privy path when a signed-in user is driving the request, so the action is attributed to their wallet and governed by their onchain role rather than a shared service credential.

Security Warnings:

  • Service tokens are shown only once during generation - store them securely immediately
  • Never commit tokens or API keys to version control
  • Never log credentials in application logs
  • Store in environment variables or secure secret management systems
  • Rotate tokens regularly (quarterly recommended)

Service Token lifecycle operations (extending, revoking) are documented in Service Tokens.