Authentication

Magma authenticates requests in two ways depending on what you're trying to do:

• API keys - required for any authenticated operation (managing offers, accepting orders as a seller, reading your own purchases or sales).
• Session keys - issued automatically when an anonymous buyer calls liquidity.buy without an API key. Lets the same anonymous user track and pay for their order without ever signing up.

The endpoint is the same for both:

https://magma.amboss.tech/graphql

1. API Keys

API keys are tied to your Amboss account and authorise every authenticated query and mutation.

Create a key

Generate one at account.amboss.tech/settings/api-keys. Treat it like a password - store it in your secret manager and never commit it to source control.

Send the key

Pass it as a Bearer token on every authenticated request.

Authorization: Bearer YOUR_API_KEY

curl -X POST https://magma.amboss.tech/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AMBOSS_API_KEY" \
  -d '{"query":"query { user { id email } }"}'

import { GraphQLClient } from "graphql-request";

const magma = new GraphQLClient("https://magma.amboss.tech/graphql", {
  headers: {
    Authorization: `Bearer ${process.env.AMBOSS_API_KEY}`,
  },
});

2. Session keys (anonymous buyers)

The liquidity.buy and liquidity.create_subscription mutations are public - you can call them without an API key. When you do, Magma creates a lightweight session account for you and returns its session key in the response.

mutation BuyLiquidity($input: LiquidityOrderInput!) {
  liquidity {
    buy(input: $input) {
      account {
        id
        session_key
      }
      order { transaction_id }
      payment { redirect_url lightning_invoice }
    }
  }
}

The response includes:

{
  "data": {
    "liquidity": {
      "buy": {
        "account": {
          "id": "54b9e82d-39d0-42b9-9229-f67786cdf145",
          "session_key": "b65b867c345468a0a2e07b3b86aa3078"
        }
      }
    }
  }
}

Reusing the session key

Send it back on subsequent calls as a Bearer token, exactly like an API key. You can use it to:

• Track the order you just created (user.market.orders.get_order)
• Buy more liquidity from the same anonymous identity
• Read transactions tied to this session

Authorization: Bearer b65b867c345468a0a2e07b3b86aa3078

3. What needs which credential

4. Rotating a key

Revoke and recreate keys at account.amboss.tech/settings/api-keys. Revocation takes effect immediately. There's no live-rotation grace period, so deploy the new key first, then revoke the old one.

Next steps

• Getting Started - your first authenticated API call
• Buy Liquidity - the public buy mutation
• Sell Liquidity - authenticated seller operations
• Errors - what to do when auth fails