canonical: https://jentic.com/apis/billfold.app/billfold

# Billfold App Billfold ID API

The Billfold ID API is the single point of authentication for Billfold's wallet, pay, and public services, issuing and validating the JWT access tokens that authorize calls to them. It exposes an access-token endpoint, a token-check endpoint that confirms whether a token is still valid, and a status endpoint for health checks. Tokens are passed as a bearer JWT in the Authorization header.

## For AI agents

Obtain and validate the JWT access tokens that authenticate calls to Billfold services, and check whether the Billfold ID service is running.

## Scope

Does not handle payments, wallet balances, or user profile storage. Use for issuing and validating Billfold access tokens only.

## Capabilities

- Obtain a JWT access token for authenticating against Billfold services
- Validate an existing access token to confirm it is still active
- Check the running status of the Billfold ID service

## Use cases

### Agent Authentication for Billfold Services

An AI agent that needs to call Billfold's wallet or pay services first obtains a JWT access token through the Billfold ID API, then presents it as a bearer token on subsequent calls. Through Jentic the agent can fetch the token without a developer wiring the authentication handshake by hand.

Example prompt: Request an access token from the Billfold ID API and store it for use as a bearer token on wallet calls

### Token Validation Before a Transaction

Before authorizing a sensitive action, a service checks that the caller's token is still valid. The Billfold ID API's token-check endpoint confirms whether a supplied access token is active, so an agent can gate an operation on a fresh validation rather than a stale assumption.

Example prompt: Submit an access token to the check-token endpoint and proceed only if it reports the token is valid

### Service Health Monitoring

The Billfold ID API exposes a status endpoint that reports whether the authentication service is running, letting an agent or monitor confirm availability before attempting a token request.

Example prompt: Call the status endpoint and alert if the Billfold ID service is not running

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/status` | Report the API running status |
| GET | `/token` | Get an access token |
| POST | `/check-token` | Validate an access token |

## Key resources

- **Tokens** — Obtain access tokens and validate whether a token is still active
- **Status** — Report whether the Billfold ID service is running

## Why Jentic

- **Setup:** Wiring Billfold ID by hand means obtaining a JWT, formatting it as a bearer value in the Authorization header, and refreshing it before it expires. Through Jentic you install once, import Billfold ID from the API Directory, store your credential once, and your agent calls it.
- **Permission scoping:** Billfold ID carries the token in the request header rather than in the URL path, so rules bound which operations your agent may call, not which token. You choose the operations it may call, so you can allow the access-token and token-check operations and leave others out unless you add them.
- **Credential handling:** Your Billfold credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'get a billfold access token' or 'validate a token', and Jentic returns the matching Billfold ID operation with its input schema so the agent calls the right endpoint.

## Related APIs

- **Stytch API** — Stytch is a full authentication platform with passwordless, OAuth, and session management, where Billfold ID issues tokens for Billfold's own services.
- **FusionAuth API** — FusionAuth is a self-hostable identity provider with user management and token issuance, a broader scope than Billfold ID's service tokens.
- **Connect2id Server API** — Connect2id provides OpenID Connect and OAuth 2.0 server operations that pair with token-based authentication like Billfold ID.

## FAQ

### What authentication does the Billfold ID API use?

The Billfold ID API authenticates with a JSON Web Token passed as a bearer value in the Authorization header, in the format 'Bearer {token}', per its OpenAPI spec. You obtain that token from the access-token endpoint and can confirm it is still valid with the token-check endpoint. Through Jentic the token is stored encrypted by your own Jentic One instance and injected at call time.

### Is there a Billfold ID API MCP server?

You don't need an MCP server to give your agent the Billfold ID API. Jentic connects it directly from the API Directory: import it, store your token once, and your agent obtains and validates access tokens as it needs them.

### Can I limit what my agent is allowed to do with the Billfold ID API?

Yes. You choose the operations your agent may call, so you can allow the token and check-token operations it needs and leave anything else out. Every call it makes is logged for review.

### Can I check whether an access token is still valid with the Billfold ID API?

Yes. The token-check operation takes an access token and reports whether it is still active, so an agent can validate a token before it authorizes a sensitive action.

### How do I get a Billfold access token through Jentic?

Search Jentic for 'get a billfold access token', which returns the token operation with its input schema. Add the Billfold ID API from the Jentic API Directory and store your credential once. To run it on your own infrastructure, install Jentic One from its GitHub repo.