Security Best Practices

This guide covers security best practices for integrating Grantex into production applications. Following these recommendations helps protect your users, agents, and data.

Token Storage

Grant tokens are RS256 JWTs. Where you store them depends on your threat model:

Strategy	When to use	Notes
In-memory	Short-lived agent tasks (minutes)	Token is lost on process restart — safest default
Encrypted session store	Multi-step workflows across requests	Use AES-256-GCM; never store tokens in plaintext
Encrypted cache (Redis)	High-throughput services sharing tokens	Set TTL to match token expiry; use TLS in transit

Never store grant tokens in browser localStorage, cookies, or client-side storage. Grant tokens are meant for server-side agent code only.

Refresh Token Storage

Refresh tokens have a 30-day TTL and are single-use. Store them with the same care as API keys:

Encrypt at rest (e.g., envelope encryption with a KMS)
Restrict access to the service that performs token refresh
Never log refresh tokens — redact them in your logging pipeline

Scope Design

Design scopes using the resource:action pattern with least privilege:

# Good — narrow, specific
calendar:read
payments:initiate:max_500
files:read:folder_abc

# Bad — overly broad
calendar
full_access
admin

Principles:

Request only what you need — agents should declare the minimum scopes required for their task
Prefer read over write — if the agent only needs to read data, don’t request write access
Use parameterized scopes — payments:initiate:max_500 is safer than payments:initiate
Review scope requests in the consent UI — users see exactly what the agent is requesting

Revocation Handling

Tokens can be revoked at any time by the user or developer. Your agent should handle revocation gracefully:

import { Grantex, GrantexAuthError } from '@grantex/sdk';

async function callWithGrant(grantToken: string, fn: () => Promise<void>) {
  try {
    await fn();
  } catch (err) {
    if (err instanceof GrantexAuthError && err.statusCode === 401) {
      // Token was revoked — stop the agent gracefully
      console.log('Grant token revoked, halting agent');
      return;
    }
    throw err;
  }
}

from grantex import GrantexAuthError

def call_with_grant(grant_token: str, fn):
    try:
        fn()
    except GrantexAuthError as err:
        if err.status_code == 401:
            print("Grant token revoked, halting agent")
            return
        raise

Best practices:

Listen for the grant.revoked webhook event to react in real time
On 401, do not retry — the token has been permanently invalidated
Clean up any cached tokens after revocation

Delegation Security

When delegating grants to sub-agents (SPEC §9):

Minimize delegation depth — each layer adds risk. Keep delegationDepth as low as possible
Always narrow scopes — the sub-agent should have fewer scopes than the parent
Verify the chain — use verifyGrantToken() to inspect parentAgentDid and delegationDepth claims
Set short expiry — delegated grants should expire before the parent grant

// Good: narrowing scopes on delegation
const delegated = await grantex.grants.delegate({
  parentGrantToken: parentToken,
  subAgentId: subAgent.id,
  scopes: ['calendar:read'],  // subset of parent's ['calendar:read', 'calendar:write']
  expiresIn: '1h',            // shorter than parent's 24h
});

PKCE

Always use PKCE (Proof Key for Code Exchange) with S256 in production:

import { Grantex, generatePkce } from '@grantex/sdk';

const grantex = new Grantex({ apiKey: process.env.GRANTEX_API_KEY });
const pkce = generatePkce();

const auth = await grantex.authorize({
  agentId: agent.id,
  userId: 'user_123',
  scopes: ['files:read'],
  codeChallenge: pkce.codeChallenge,
  codeChallengeMethod: 'S256',
});

// Later, when exchanging the code:
const token = await grantex.tokens.exchange({
  code: callbackCode,
  agentId: agent.id,
  codeVerifier: pkce.codeVerifier,
});

from grantex import Grantex, AuthorizeParams, ExchangeTokenParams, generate_pkce

pkce = generate_pkce()

with Grantex(api_key="gx_live_...") as client:
    auth = client.authorize(AuthorizeParams(
        agent_id="agt_abc",
        user_id="user_123",
        scopes=["files:read"],
        code_challenge=pkce.code_challenge,
        code_challenge_method="S256",
    ))

    token = client.tokens.exchange(ExchangeTokenParams(
        code=callback_code,
        agent_id="agt_abc",
        code_verifier=pkce.code_verifier,
    ))

PKCE prevents authorization code interception attacks. Without it, an attacker who intercepts the code can exchange it for a grant token.

Audit Trail Best Practices

The audit log is your forensic record. Use it proactively:

Log every sensitive action — file access, payment initiation, data deletion
Include metadata — resource IDs, amounts, user-facing descriptions
Use appropriate status values — success, failure, or blocked
Query audit entries regularly — detect anomalies before they become incidents
Enable the anomaly detection worker — it flags rate spikes, high failure rates, and off-hours activity automatically

await grantex.audit.log({
  agentId: agent.id,
  agentDid: agent.did,
  grantId: grant.id,
  principalId: grant.principalId,
  action: 'payments:initiate',
  metadata: { amount: 250, currency: 'USD', recipient: 'vendor_xyz' },
  status: 'success',
});

Key Rotation

Rotate your Grantex API key periodically using POST /v1/keys/rotate
After rotation, update all services that use the old key
The old key is immediately invalidated — plan for a brief deployment window

Summary Checklist

Store tokens in memory or encrypted server-side stores

Use resource:action scope format with least privilege

Handle 401 gracefully — never retry revoked tokens

Minimize delegation depth and always narrow scopes

Always use PKCE S256 in production

Log all sensitive agent actions to the audit trail

Enable webhooks for grant.revoked events

Rotate API keys periodically

​Token Storage

​Refresh Token Storage

​Scope Design

​Revocation Handling

​Delegation Security

​PKCE

​Audit Trail Best Practices

​Key Rotation

​Summary Checklist

Token Storage

Refresh Token Storage

Scope Design

Revocation Handling

Delegation Security

PKCE

Audit Trail Best Practices

Key Rotation

Summary Checklist