Session Tokens

Short-lived, scoped credentials for production environments. Mint from an API key, use for a limited time, and let them auto-expire.

What are session tokens?

A session token is a time-limited credential derived from your API key. It carries a subset of the parent key's permissions and automatically expires after the specified TTL. Session tokens are ideal for CI runners, serverless functions, and any short-lived environment where you want to limit the blast radius of a leaked credential.

Minting a session token

Via the SDK

mint-token.tstypescript

import { FyVault } from "@fyvault/sdk";

const fv = new FyVault({
  accessToken: process.env.FYVAULT_API_KEY,  // fv_live_...
  orgId: "org_acme",
});

const session = await fv.accessTokens.create({
  ttlSeconds: 900,          // 15 minutes
  scopes: ["secrets:read"], // optional scope restriction
});

console.log(session.token);     // fvsess_...
console.log(session.expiresAt); // ISO 8601 timestamp

Via the API

mint-token.shbash

curl -X POST https://api.fyvault.com/api/v1/orgs/org_acme/access-tokens \
  -H "Authorization: Bearer fv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"ttlSeconds": 900, "scopes": ["secrets:read"]}'

Using a session token

Use the session token exactly like an API key — pass it as a Bearer token or to the SDK constructor.

use-token.tstypescript

// In a different context (e.g. a CI runner)
const runner = new FyVault({
  accessToken: session.token,  // fvsess_...
  orgId: "org_acme",
});

const dbUrl = await runner.secrets.getValueByName("db-url");

Revoking a session token

Session tokens auto-expire after their TTL, but you can revoke them immediately if needed.

revoke-token.tstypescript

// Revoke by token ID
await fv.accessTokens.revoke(session.id);

// Or via the API
// DELETE /orgs/:org_id/access-tokens/:token_id

Token type reference

Prefix	Type	Use case
fv_live_	API key	Long-lived org-level access
fvsess_	Session token	Short-lived scoped access
fvag_	Agent credential	AI agent access with rate limits
fvprov_	Provider token	Internal services pushing credentials
fvbg_	Break-glass token	Emergency access (max 4h TTL)

Security Properties

Time-to-live (TTL)

Configurable from 60 seconds to 24 hours. Tokens auto-expire after TTL regardless of usage.

Hash at rest

Token values are SHA-256 hashed before storage. FyVault never stores plaintext session tokens in the database.

Scope restriction

Tokens can be scoped to a subset of the parent key's permissions (e.g. secrets:read only).

Audit logging

Every operation performed with a session token is logged in the audit trail with the token ID and parent key reference.

Revocable

Tokens can be revoked immediately via the API or SDK, before their natural TTL expiry.

Recommended Pattern

For production environments, mint a session token at process startup and refresh it before expiry or on a 401 response.

recommended-pattern.tstypescript

import { FyVault } from "@fyvault/sdk";

const fv = new FyVault({
  accessToken: process.env.FYVAULT_API_KEY,
  orgId: "org_acme",
});

// Mint at startup
let session = await fv.accessTokens.create({ ttlSeconds: 3600 });
let client = new FyVault({ accessToken: session.token, orgId: "org_acme" });

// Refresh before expiry (e.g. in a setInterval)
setInterval(async () => {
  session = await fv.accessTokens.create({ ttlSeconds: 3600 });
  client = new FyVault({ accessToken: session.token, orgId: "org_acme" });
}, 50 * 60 * 1000); // Refresh every 50 minutes