Scoped Tokens

28 scoped faces. Least privilege by default.

Scoped tokens are fine-grained API keys limited to specific faces and entities. Each token can only call the methods you allow — nothing more. If a token leaks, the blast radius is minimal.

Token Anatomy

Readable by design.

Every scoped token encodes its permissions in the key itself. You can tell at a glance which entity and face a token belongs to.

sk_entity_face_random

Prefix

Scoped key identifier

Entity

acme-corp

Bound to one entity

Face

billing

Limited to one face

Random

a1b2c3d4

Cryptographic random

Available Scopes

28 faces. 28 scopes.

aiauthbillingstoragesearchmediacomputeemailsmspushnotificationwebhookdatabasevectorcachequeueanalyticscronworkflowformstemplatepdfconfigsecretslogsmetricscdndns

Each scope grants access to all methods within that face. Multi-scope tokens are supported — combine faces as needed.

Token Management

Create, rotate, revoke.

Create a scoped token

create-token.ts

// Create a scoped token — billing-only access
const token = await ee.auth.createToken({
  name: 'billing-service',
  scopes: ['billing'],
  entity: 'acme-corp',
  expiresIn: '90d',
})

console.log(token.key)
// => "sk_acme-corp_billing_a1b2c3d4e5f6"

// This token can ONLY call ee.billing.* methods
// Any other face call returns 403 Forbidden

Rotate and revoke

rotate-token.ts

// Rotate a token — old token stays valid for the grace period
const rotated = await ee.auth.rotateToken({
  tokenId: token.id,
  gracePeriod: '24h', // old token works for 24 more hours
})

console.log(rotated.newKey)
// => "sk_acme-corp_billing_x9y8z7w6v5u4"

// Revoke immediately when you don't need the grace period
await ee.auth.revokeToken({ tokenId: token.id })

Best Practices

Security-first token hygiene.

Never use root tokens in client code

Root tokens have access to every face. Use scoped tokens in production — limit blast radius if a token is compromised.

Rotate every 90 days

Set expiry dates on all tokens. Use the grace period during rotation so your services don’t drop requests.

Short-lived tokens for webhooks

Webhook handler tokens should expire in hours, not months. Generate a new one per deployment cycle.

One token per service

Don’t share tokens between services. Each microservice gets its own scoped token with only the faces it needs.

Audit token usage

Every token call is logged. Use ee.audit.query to review which tokens are calling which faces — and revoke unused ones.

Use environment variables

Never hardcode tokens. Store them in your secrets manager or environment variables. The SDK reads from process.env by default.

Secure your integration.

Start with scoped tokens from day one. Your future self will thank you.

Quickstart Guide See Patterns

SDK