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

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:8080/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 ------>|

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 (SSE or polling) to detect unexpected activity — transfers you did not initiate, objects created outside your expected paths, etc.

Error Handling

Errors follow a consistent structure with a machine-readable code and a human-readable message.

Error Codes

Example Error Response

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