🔐 @saptools/cf-xsuaa

Stop copy-pasting XSUAA tokens from the BTP cockpit.

Fetch XSUAA credentials and OAuth2 access tokens from SAP BTP Cloud Foundry apps — straight from your terminal, with intelligent caching built in.

Install • Quick Start • CLI • FAQ

✨ Features

• 🔑 Zero-config OAuth2 — fetches client_credentials tokens straight from the XSUAA binding of any CF app
• 💾 Smart caching — reuses tokens until they expire so you do not hand out stale JWTs
• 🧩 CLI & API — drop into shell scripts, Node pipelines, or your favorite test runner
• 🔗 CF-aware — resolves CF API endpoints from region keys via @saptools/cf-sync, no manual URLs
• 🔒 Type-safe — shipped with full TypeScript definitions
• 🪶 Tiny — one dependency (commander) and zero runtime magic

📦 Install

# Global CLI
npm install -g @saptools/cf-xsuaa

# Or as a dependency
npm install @saptools/cf-xsuaa
# pnpm add @saptools/cf-xsuaa
# yarn add @saptools/cf-xsuaa

[!NOTE] Requires Node.js ≥ 20 and the cf CLI on PATH. For the first secret fetch, set SAP_EMAIL and SAP_PASSWORD.

🚀 Quick Start

# 1. Tell cf-xsuaa who you are (only needed for the first secret fetch)
export SAP_EMAIL="[email protected]"
export SAP_PASSWORD="your-sap-password"

# 2. Grab a token (auto-fetches the XSUAA binding on first call, caches it forever)
cf-xsuaa get-token-cached \
  --region ap10 --org my-org --space dev --app my-srv

That's it. Copy the printed JWT into curl, Postman, bruno, or wherever you need it. Next call reuses the cached token until it expires.

🧰 CLI

Every command identifies an app with the same four flags:

| Flag | Description | Example | | --- | --- | --- | | -r, --region <key> | CF region key | ap10, eu10, us10 | | -o, --org <name> | CF org name | my-org | | -s, --space <name> | CF space name | dev | | -a, --app <name> | CF app name | my-srv |

🔎 cf-xsuaa fetch-secret

Pull the XSUAA client credentials out of the app's VCAP_SERVICES and cache them to disk. Run this once per app, or whenever the binding rotates.

cf-xsuaa fetch-secret --region ap10 --org my-org --space dev --app my-srv

🎟️ cf-xsuaa get-token

Fetch a fresh OAuth2 client_credentials token and print the JWT to stdout. Auto-runs fetch-secret first if the binding isn't cached yet.

cf-xsuaa get-token --region ap10 --org my-org --space dev --app my-srv

⚡ cf-xsuaa get-token-cached

Return the cached token if it's still valid, otherwise fetch a new one. This is what you want 99% of the time.

TOKEN=$(cf-xsuaa get-token-cached --region ap10 --org my-org --space dev --app my-srv)
curl -H "Authorization: Bearer $TOKEN" https://my-srv.cfapps.ap10.hana.ondemand.com/api/health

[!TIP] Cached tokens are refreshed before they become stale, so callers do not receive a JWT that is about to expire.

📁 Output File

All state lives in a single JSON file under your home directory:

~/.saptools/xsuaa-data.json

{
  "version": 1,
  "entries": [
    {
      "region": "ap10",
      "org": "my-org",
      "space": "dev",
      "app": "my-srv",
      "credentials": {
        "clientId": "sb-xsappname!t123",
        "clientSecret": "<redacted>",
        "url": "https://my-org.authentication.ap10.hana.ondemand.com",
        "xsappname": "my-app!t123"
      },
      "token": {
        "accessToken": "eyJhbGciOi...",
        "expiresAt": "2026-04-18T12:34:56.000Z"
      },
      "fetchedAt": "2026-04-18T12:20:00.000Z"
    }
  ]
}

[!IMPORTANT] Prefer the CLI or exported APIs over parsing this file directly — the on-disk format is an implementation detail.

❓ FAQ

No. Those are only read when cf-xsuaa has to refresh the VCAP-bound client secret. Once the secret is cached, token refreshes go straight to the UAA with client_credentials — no SAP user credentials required.

cf oauth-token returns your personal UAA token. cf-xsuaa returns the app's own service token (issued to the XSUAA clientId in VCAP_SERVICES), which is what you actually need when calling the app's protected endpoints.

No. ~/.saptools/xsuaa-data.json contains clientSecret and live JWTs. It lives under your home directory and should never be checked into git.

Run cf-xsuaa fetch-secret again with the same --region/--org/--space/--app flags and the entry will be overwritten.

🛠️ Development

From the monorepo root:

pnpm install
pnpm --filter @saptools/cf-xsuaa build
pnpm --filter @saptools/cf-xsuaa typecheck
pnpm --filter @saptools/cf-xsuaa test:unit
pnpm --filter @saptools/cf-xsuaa test:e2e

The e2e suite auto-discovers a real CF app with an xsuaa service binding by scoring candidates from ~/.saptools/cf-structure.json. To pin a specific target:

export E2E_TARGET="ap10/my-org/my-space/my-srv"

🌐 Related

• 📦 @saptools/cf-sync — sync the CF region → org → space → app tree to disk
• 🗂️ saptools monorepo — the full toolbox

👨‍💻 Author

dongtran ✨

📄 License

MIT

Made with ❤️ to make your work life easier!