storacha-storage-layer-access.md

In Storacha, you don't have a simple "bearer token". You need two things:

1. Identity (Key): Who you are (Private Key).
2. Permission (Proof): Proof that you are allowed to access the Space.

Most "API Key" confusion comes from missing the Proof part. See this example:

import { create } from '@storacha/client'
import { parse as parseProof } from '@storacha/client/proof'
import { StoreMemory } from '@storacha/client/stores'
import { Signer } from '@ucanto/principal/ed25519'

async function main() {
  // 1. Load your Private Key (Your Identity)
  // Create the KEY and AGENT_DID from the CLI: `storacha key create --json` and set the key into env.STORACHA_KEY
  const keyString = process.env.STORACHA_KEY
  if (!keyString) throw new Error('Missing STORACHA_KEY env var')
  
  const signer = Signer.parse(keyString)
  console.log(`Authenticating as DID: ${signer.did()}`)

  // 2. Load your Delegation Proof (this is your "token" to access the Space)
  // Generate this from the CLI: `storacha delegation AGENT_DID --base64` 
  // AGENT_DID is the DID generated in step 1
  // The Storacha account you logged in via CLI is delegating access to that AGENT_DID - so you can access the storage layer programmatically
  const proofString = process.env.STORACHA_PROOF
  if (!proofString) throw new Error('Missing STORACHA_PROOF env var')
  
  const proof = await parseProof(proofString)
  const space = proof.capabilities[0].with
  console.log(`Loaded Proof for Space: ${space}`)

  // 3. Create the Client with the Identity and Proofs
  // IMPORTANT: We use StoreMemory() to avoid conflicts with your global CLI session
  const client = await create({
    principal: signer,
    store: new StoreMemory()
  })
  
  // 4. Verify we are who we think we are
  console.log(`Client DID: ${client.agent.did()}`)
  if (client.agent.did() !== signer.did()) {
      throw new Error('Client DID does not match Signer DID!')
  }

  // 5. Register the Proof (Delegation)
  // We use addSpace() because this proof grants access to a Space
  await client.addSpace(proof)
  await client.setCurrentSpace(space)

  // 6. List Uploads
  const response = await client.capability.upload.list({
    limit: 5,
    cursor: undefined // Use this for pagination
  })
  console.log(response)
  if (response.results) {
    for (const item of response.results) {
      console.log(`   - ${item.root} (${new Date(item.updatedAt).toISOString()})`)
    }
  } else {
    console.error('List failed:', response.error)
  }
}

main().catch(console.error)