Scoped Tokens & Permissions

Arca uses an IAM-style, resource/capabilities permission model inspired by AWS. Both scoped JWT tokens (for end-users) and scoped API keys (for services) carry policy statements that grant specific actions on specific Arca path patterns.

Policy Model

A scope contains one or more policy statements. Each statement has an effect ("Allow" or "Deny"), a set of actions, and a set of resources (Arca object path patterns):

{
  "statements": [
    {
      "effect": "Allow",
      "actions": ["arca:TransferFrom", "arca:ReceiveTo"],
      "resources": ["/users/u123/*"]
    },
    {
      "effect": "Allow",
      "actions": ["arca:Read"],
      "resources": ["*"]
    },
    {
      "effect": "Deny",
      "actions": ["arca:*"],
      "resources": ["/_internal/*"]
    }
  ]
}

Anything not explicitly allowed is denied by default. Deny statements act as safety rails — they override any Allow statements. Use them to protect sensitive paths even when a broad Allow is in effect.

Action Catalog

Retrieve the full catalog programmatically via GET /api/v1/permissions (no auth required).

Object Lifecycle

Balance (directional)

Read / Observe

Exchange

Convenience Aliases

Aliases expand to individual actions. Named aliases are expanded at mint time (stored in the JWT). The wildcard arca:* is stored as-is and matches any action at check time.

Resource Patterns

• /treasury/usd — exact match
• /users/* — matches the prefix and all paths below it
• * — matches all resources

Path safety note: Arca paths have no directory-traversal semantics. The segments . and .. are treated as literal characters. There is no path normalization — what you see is what matches. This is a deliberate security invariant.

Authorization Principles

1. Deny by default. Anything not explicitly granted by an Allow statement is denied.
2. Explicit Deny overrides Allow. If any Deny statement matches an (action, resource) pair, the request is blocked — regardless of any Allow statements. Use Deny as a safety rail to protect sensitive paths (e.g., /_internal/*).
3. Actions are directional and per-resource. For operations touching multiple objects, each side is checked independently. A transfer checks arca:TransferFrom on the source and arca:ReceiveTo on the target.
4. Inbound permissions are unified. arca:ReceiveTo covers deposits, transfer credits, and sweeps. The balance outcome is identical regardless of channel. Outbound actions (arca:TransferFrom, arca:WithdrawFrom) remain separate because they cross different trust boundaries.
5. Delete + sweep is compound authorization. Deleting an object with balance requires arca:DeleteObject on the source and arca:ReceiveTo on the sweep target. Without a sweep target, arca:DeleteObject alone suffices for zero-balance objects.
6. Realm is a boundary, not a resource. Scoped tokens are locked to one realm. Resource patterns do not encode realm — this simplifies matching.

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expiresAt": "2026-02-14T15:00:00Z"
  }
}

# Builder's backend mints a token for user "alice"
curl -X POST http://localhost:3052/api/v1/auth/token \
  -H "Authorization: Bearer arca_78ae7276_..." \
  -H "Content-Type: application/json" \
  -d '{
    "realmId": "6d25623e-...",
    "sub": "alice",
    "scope": {
      "statements": [
        {
          "effect": "Allow",
          "actions": ["arca:Read"],
          "resources": ["*"]
        },
        {
          "effect": "Allow",
          "actions": ["arca:TransferFrom", "arca:ReceiveTo"],
          "resources": ["/users/alice/*"]
        },
        {
          "effect": "Deny",
          "actions": ["arca:*"],
          "resources": ["/_internal/*"]
        }
      ]
    },
    "expirationMinutes": 30
  }'

{
  "success": true,
  "data": {
    "entries": [
      {
        "id": "...",
        "builderId": "...",
        "eventType": "token_minted",
        "actorType": "builder",
        "actorId": "...",
        "realmId": "...",
        "subject": "alice",
        "scopeSummary": "{...}",
        "tokenJti": "...",
        "expiresAt": "2026-02-21T15:00:00Z",
        "success": true,
        "operationCount": 12,
        "createdAt": "2026-02-21T14:00:00Z"
      }
    ],
    "total": 42
  }
}

{
  "success": true,
  "data": {
    "credentialType": "scoped_token",
    "credentialId": "abc-123-jti",
    "subject": "alice",
    "scope": "{\"statements\":[...]}",
    "fullAccess": false,
    "createdAt": "2026-02-21T14:00:00Z",
    "expiresAt": "2026-02-21T15:00:00Z"
  }
}

Scope Enforcement

When a scoped token (or scoped API key) is used, the API enforces:

1. Realm lock: Scoped tokens can only access the realm specified at mint time. Requests to other realms return 403 FORBIDDEN.
2. Policy evaluation: Each operation produces one or more (action, resource) pairs. For each pair: (a) if any Deny statement matches, access is blocked; (b) if any Allow statement matches, access is granted; (c) otherwise, access is denied (implicit deny). All pairs must pass for the request to succeed.
3. Resource matching: Requested paths must match at least one pattern in the granting statement. Patterns ending in /* match all descendants.

Integration Flow

BuilderBackend          ArcaAPI              EndUserFrontend
     |                     |                        |
     |--- POST /auth/token --->|                    |
     |<-- scoped JWT ----------|                    |
     |                         |                    |
     |--- hand JWT to user --->|                    |
     |                         |                    |
     |                         |<-- POST /transfer -|
     |                         |   (Bearer scoped)  |
     |                         |-- verify + enforce -|
     |                         |                    |
     |                         |--- response ------>|

Team & Org Management

Every Arca account belongs to an organization. An org owns one or more realms (demo, production) and hasmembers with defined roles. API keys are org-scoped and grant access to all realms the key holder can reach.

Roles

Org members have one of four roles, listed from most to least privileged:

When a member accesses a realm, their org role is mapped to a set of arca:* permissions automatically. Owners and admins get unrestricted access. Developers can do everything except delete objects. Viewers are read-only.

Invitations

Only admins and owners can invite new members. The flow:

1. Invite — an admin calls POST /api/v1/org/invitations with the recipient's email and desired role. The invitee's role cannot exceed the inviter's.
2. Email — the recipient receives an invitation link with a JWT token (valid ~7 days).
3. Preview — the recipient can view the org name and role without signing in (GET /api/v1/invitations/{token}/preview).
4. Accept — the recipient signs in and accepts the invitation (POST /api/v1/invitations/{token}/accept). They become a member immediately.

Admins can list pending invitations with GET /api/v1/org/invitations and revoke them with DELETE /api/v1/org/invitations/{id}. Recipients can check their own pending invitations with GET /api/v1/invitations/pending.

Realm-Type Scoping

When inviting or updating a member, you can restrict them to specific realm types (e.g., demo only). A scoped member can only access realms matching their allowed types.

This is useful for giving contractors or junior developers access to demo environments without exposing production data.

API Key Management

API keys are org-scoped and authenticate server-to-server calls. Manage them through the portal or API:

• Create: POST /api/v1/api-keys — returns the key value once. Store it securely.
• List: GET /api/v1/api-keys — shows all keys (values are masked).
• Revoke: DELETE /api/v1/api-keys/{id} — immediately invalidates the key.

To rotate a key: create a new one, update your application to use it, verify it works, then revoke the old key. Never revoke before your application has switched over.

Signing Keys (Operation Non-Repudiation)

Signing keys add a layer of cryptographic non-repudiation to API operations. While API keys prove authentication (who is making the request), signing keys prove authorization (that the builder explicitly approved this specific operation with these specific parameters).

Each signing key is an Ed25519 keypair. The builder generates the keypair locally and registers only the public key with Arca. The private key never leaves the builder's environment.

Key Lifecycle

Grace Period

When a second (or subsequent) key is registered, it enters a 72-hour grace period before activation. This window allows the builder (or Arca) to detect and cancel unauthorized key registrations. Practice realms skip the grace period for faster iteration.

During activation, the previously active key is automatically transitioned to rotated state.

Audit Trail

Every key lifecycle event (registration, activation, revocation, freeze) is recorded in a hash-chained event log. Each event includes a SHA-256 hash linking it to the previous event, creating a tamper-evident chain. View key events via GET /api/v1/signing-keys/:id/events.

Key Generation

Generate an Ed25519 keypair using OpenSSL or any Ed25519 library:

# Generate private key
openssl genpkey -algorithm Ed25519 -out signing-key.pem

# Extract public key (base64)
openssl pkey -in signing-key.pem -pubout -outform DER | base64

Or in Node.js:

import { generateKeyPairSync } from 'crypto';
const { publicKey, privateKey } = generateKeyPairSync('ed25519');
const pubKeyBase64 = publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
// Register pubKeyBase64 via POST /api/v1/signing-keys

When to Use Signing Keys

• Production realms: Signing keys provide cryptographic evidence that all fund movements and trades were authorized by the builder, protecting both the builder and Arca.
• Compliance: Signed operations create an auditable chain of builder intent that can be independently verified.
• Multi-person teams: When multiple team members have API access, signing keys attribute specific actions to specific individuals.

Common Patterns

Set up a 5-person startup

The founder creates the org (becomes owner). Invite the CTO and lead engineer as admins (they can manage members and API keys). Invite two developers as developers (full access except object deletion).

Give a contractor demo-only access

Invite the contractor as a developer with realm-type scope restricted to demo. They can build and test against demo realms but cannot see or touch production data.

Rotate API keys safely

1. Create a new API key in the portal or via the API.
2. Update your application's environment variables to use the new key.
3. Deploy and verify requests succeed with the new key.
4. Revoke the old key.

Ownership Transfer

Only the current owner can transfer ownership. The target must already be an admin. After transfer, the previous owner is demoted to admin.

# CLI
arca org transfer-ownership --target-user-id <userId>

# API
POST /api/v1/org/transfer-ownership
{ "targetUserId": "<userId>" }

Custody Model

Arca manages private keys, transaction signing, and on-chain settlement on behalf of builders. You interact with funds through the SDK and API — you never handle private keys or sign transactions directly.

Three-Layer Architecture

Who Controls What

Arca holds all private keys and has technical control over all funds at every layer. Builders have operational control — you decide what transactions to execute — but not cryptographic control (you cannot sign transactions directly).

Builder vs. Arca Responsibilities

How This Compares

For Your Legal Team

Architecture Patterns

When integrating Arca into your product, the key architectural decision is which operations your end-user's frontend performs directly against Arca (using a scoped token) versus which ones route through your backend (using an API key).

The guiding principle: Arca scopes restrict which resources and which actions, but they cannot enforce business logic. If you need to check anything beyond “does this user have permission on this resource” before allowing a write — KYC status, daily limits, manager approval, balance checks in your own system — that write must go through your backend.

Recommended: Read-Only Frontend Tokens

Mint scoped tokens with arca:Read scope for your frontend. This alias includes all read actions plus arca:Subscribe, so real-time streaming works natively. The frontend gets:

• Real-time balance, position, and order-status streaming via WebSocket
• Object, operation, event, and delta reads
• Exchange data reads (order book, positions, fills)
• Portfolio aggregation and P&L

All mutations (transfers, deposits, withdrawals, object lifecycle) go through your backend using an API key. This gives you:

• Business logic enforcement before any mutation — KYC checks, daily limits, approval flows
• Complete server-side audit trail of what was requested and why
• Minimal blast radius if a frontend token is compromised — read-only means no fund movement

// Builder's backend — mint a read-only token for the frontend
const { token } = await admin.mintToken({
  realmId: realm.id,
  sub: user.id,
  scope: {
    statements: [
      { effect: 'Allow', actions: ['arca:Read'], resources: ['*'] },
    ],
  },
  expirationMinutes: 30,
});
// Return 'token' to the frontend

// End-user's frontend — read and stream, no write risk
const arca = Arca.fromToken(token);
const balances = await arca.watchBalances('/users/alice/');
const ops = await arca.watchOperations();

Advanced: Selective Write Scopes

For specific cases where the backend hop adds unacceptable latency, you can selectively add write actions to the frontend token. Consider the risk gradient:

Decision Table

Production Readiness Checklist

A step-by-step guide for moving from a demo realm to production. Complete these items before launching your integration to real users.

1. Create a production realm. Use POST /api/v1/realms with type: "production" or create one from the Portal. Production realms connect to live venue infrastructure — objects, balances, and operations are persistent and irreversible.
2. Generate separate production API keys. Never reuse demo API keys in production. Create dedicated keys for each environment and store them securely (environment variables, secrets manager). Rotate keys periodically by creating a new key, migrating, then revoking the old one.
3. Scope frontend tokens with minimal permissions. Mint scoped tokens with only the actions your frontend needs — typically arca:Read and streaming. Keep mutations (transfers, orders, object lifecycle) on your backend using the API key. See Architecture Patterns for the recommended split.
4. Set short token expiry. Use 15–60 minute token lifetimes. On the client, use Arca.fromTokenProvider() to automatically refresh tokens before expiry — the SDK calls your provider function and reconnects the WebSocket seamlessly.
5. Configure builder fees. Set builderFeeBps on your realm settings for a default fee on all exchange orders, or pass it per-order in placeOrder(). Use feeTargets to split fee revenue to specific paths (e.g. KOL rev-share, referral programs).
6. Switch from test funding to payment links. fundAccount() and defundAccount() are dev/test helpers that mint or burn simulated funds. In production, use createPaymentLink() to generate hosted deposit and withdrawal pages for your users. Payment links handle KYC, payment processing, and settlement automatically.
7. Plan your object path hierarchy. Path structure determines how balances aggregate — changing it later requires migrating objects. Design paths to match your product model (e.g. /users/{userId}/wallet for payments, /traders/{traderId}/exchange for trading). See Path Organization.
8. Implement error handling. Catch OperationFailedError when awaiting operation handles and check error.operation.failureReason. Implement retries with stable nonces (generate the nonce once, reuse on retries). See Troubleshooting.
9. Enable real-time monitoring. Use watchOperations() to track operation lifecycle and detect failures early. Use watchBalances() to verify settlement completes. For exchange integrations, watchExchangeState() provides live margin and position data.
10. Complete the Security Pre-flight Checklist. Review every item in the Security Pre-flight Checklist below. It covers API key hygiene, path scoping, scope validation, and token minting safety.

Security Pre-flight Checklist

When exposing Arca to end-users via scoped tokens, the following items remain in the builder's domain. Arca enforces token scope at the API layer, but the builder is responsible for minting correct tokens in the first place.

1. Never expose API keys on the frontend. API keys are team-scoped with full access to every realm. Always use scoped tokens for end-user-facing code. If an API key leaks, revoke it immediately from the API Keys page.
2. Scope tokens to the user's Arca paths. When minting a token, restrict paths to the current user's subtree (e.g., /users/{userId}/*). A token with paths: ["/*"] gives access to every object in the realm.
3. Grant minimal permissions. Only include the permissions the user actually needs. Most end users need read and transfer — not delete or create.
4. Set short expiry times. Frontend tokens should expire in 15–60 minutes. The builder's backend should handle refresh by minting a new token when the current one is close to expiry.
5. Validate scope server-side before minting. The builder's backend must verify that the requesting user is entitled to the paths and permissions in the token. Arca trusts the builder to get this right — it has no knowledge of the builder's user model.
6. Do not let the frontend request its own scope. The end-user's frontend should not send the desired scope to the builder's backend. The backend should derive the scope from the user's authenticated identity and business rules.
7. Use distinct realms for dev and production. Demo realm data is simulated and has permissive defaults. Never use a demo realm for real transactions.
8. Treat operation paths as idempotency keys. If a transfer path is reused, the original result is returned (no double-spend). Build unique paths — include a nonce or UUID (e.g., /op/transfer/{userId}-{uuid}).
9. Monitor via events. Subscribe to realm events (WebSocket or polling) to detect unexpected activity — transfers you did not initiate, objects created outside your expected paths, etc.

Error Handling

Every API error returns the same JSON envelope with a machine-readable code you can match on programmatically and a human-readable message with details.

Response Envelope

Successful responses:

{
  "success": true,
  "data": { ... }
}

Error responses:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Realm name must be 100 characters or fewer",
    "errorId": "err_a1b2c3d4"
  }
}

The errorId field is a unique identifier for the error occurrence. It is always present on 5xx errors and on most 4xx errors. When contacting support about an error, include the errorId so we can locate the exact request in our logs.

Validation Errors (400)

Business Logic Errors (400)

Authentication Errors (401)

Authorization Errors (403)

Not Found Errors (404)

Conflict Errors (409)

Server Errors (5xx)

Error Handling in the SDK

The TypeScript SDK throws typed errors you can catch and inspect:

import Arca, { ArcaError, OperationFailedError } from '@arca/sdk';

const arca = new Arca({ apiKey: 'arca_...' });

try {
  const { nonce } = await arca.nonce('/transfers/payment-001');
  await arca.transfer({
    from: walletId,
    to: recipientId,
    amount: '100.00',
    nonce,
  });
} catch (err) {
  if (err instanceof OperationFailedError) {
    // Operation was created but failed during execution
    console.error('Operation failed:', err.operation.failureMessage);
  } else if (err instanceof ArcaError) {
    // API-level error — match on err.code
    switch (err.code) {
      case 'INSUFFICIENT_BALANCE':
        console.error('Not enough funds:', err.message);
        break;
      case 'IDEMPOTENCY_VIOLATION':
        console.error('Path reused with different params');
        break;
      default:
        console.error(`[${err.code}] ${err.message}`);
    }
  }
}

Troubleshooting

Common problems organized by scenario. For the full error code catalog, see the Error Handling section above.

First-Hour Mistakes

The five most common issues during initial integration:

Scoped Token Debugging

When a scoped token request is rejected with FORBIDDEN, the error message says which action was denied but does not reveal the full policy. Here's how to debug:

1. Check the error response. The message field includes the denied action (e.g. "action arca:Transfer not allowed").
2. Decode the token. Scoped tokens are JWTs. Paste yours into a JWT debugger to see the scope claim — it lists every (action, resource) pair the token grants.
3. Compare action names. The denied action must exactly match one of the scope entries. Common mismatches: using arca:Write when the endpoint requires arca:Transfer, or scoping to /users/alice/* when the request targets /users/bob/*.
4. Check path scoping. If the scope grants arca:Read on /users/alice/*, the token can read Alice's objects but not Bob's. Broaden the path to /users/* if the client needs access to multiple users.

Settlement Failure Diagnosis

When an operation reaches a failed terminal state, thefailureReason field explains why:

Failed operations are permanent — they cannot be retried directly. Create a new operation with a new nonce to retry the intent. For transfers that fail after PNR (point of no return), Arca automatically creates a compensating transaction to reverse the source debit.

Exchange Order Failures

When to Contact Arca Support

Most issues are resolvable using the error codes and troubleshooting steps above. Contact Arca support (support@arcaos.io) when:

• You receive a 5xx error that persists across retries — include the errorId
• An operation is stuck in processing state for more than 5 minutes
• Balance totals don't match what you expect after all operations have settled
• The WebSocket connection fails to reconnect after multiple attempts
• You need help designing your path hierarchy or permission model