> ## Documentation Index
> Fetch the complete documentation index at: https://docs.magic.link/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Deep dive into Core API's security architecture, JWT-bound key scheme, and implementation patterns

## Security Architecture

### AWS Nitro Trusted Execution Environment

Core API leverages AWS Nitro TEE to provide hardware-level security for all cryptographic operations. This ensures that:

* Private keys are never exposed in plaintext outside the enclave
* All cryptographic operations happen in an isolated environment
* Every key operation requires a valid, identity-bound authorization from your application before it can proceed

### JWT-Bound Key Scheme

Every wallet is cryptographically bound to a user's JWT identity at creation time. The Nitro Enclave bakes JWKS from your identity provider into the enclave image (measured in PCR0). This means JWT verification happens entirely offline inside the enclave — no external network call is needed during a signing operation.

#### Key Material

When a wallet is created, the private key is split using a **2-of-3 Shamir's Secret Sharing** scheme:

<CardGroup cols={2}>
  <Card title="Shard A (Magic)" icon="shield">
    Stored encrypted in Magic's secure infrastructure. Available for all key operations.
  </Card>

  <Card title="Shard B (Discarded)" icon="trash">
    Generated during wallet creation but immediately discarded. Not stored or returned. Recovery is handled via your identity provider's JWT.
  </Card>

  <Card title="Shard C1 (Magic)" icon="shield">
    Stored encrypted in Magic's secure infrastructure. Combined with Shard C2 to reconstruct the data key.
  </Card>

  <Card title="Shard C2 (Access Key)" icon="database">
    Returned to your application as `access_key`. Store securely in your database. Required for every signing operation.
  </Card>
</CardGroup>

In addition to the shards, the enclave internally produces a sealed blob that cryptographically ties the wallet's key material to the user's JWT identity. Every operation must supply an `op_jwt` that the enclave verifies before authorizing the request.

#### Operation Flow

**Signing / Key Reveal**

1. Your server retrieves `wallet_id` and `access_key` from your database
2. Your server obtains a short-lived `op_jwt` (max 5 min) for the user from your IdP
3. Your server calls the TEE endpoint with `op_jwt`, `wallet_id`, and `access_key`
4. The enclave verifies the JWT offline using baked-in JWKS, confirms the caller's identity matches the wallet's owner, and authorizes the operation
5. The enclave signs using the reconstructed private key; the signed result is returned

## Implementation Patterns

### Wallet Creation Flow

1. **User authenticates** with your identity provider and receives a JWT
2. **Server** calls `POST /v2/api/wallet` with `auth_jwt`, `network`, and `wallet_group_id`
3. **Server** stores the returned `wallet_id` and `access_key` in your database
4. **Server** returns the `public_address` to the client

### Signing Flow

1. **Client** initiates a transaction or signing request
2. **Server** retrieves `wallet_id` and `access_key` from your database
3. **Server** obtains a short-lived `op_jwt` for the user (max 5 min expiry)
4. **Server** calls the appropriate sign endpoint with `op_jwt`, `wallet_id`, `access_key`, and the payload
5. **Server** broadcasts or returns the signed result

<Tip>
  Always generate the `op_jwt` as close to the signing call as possible to minimize its window of validity.
</Tip>