github-starred/actual
2
0
Fork 0
mirror of https://github.com/actualbudget/actual.git synced 2026-07-16 07:04:23 -05:00
Code Issues 3.0k Packages Projects Releases 58 Wiki Activity

[GH-ISSUE #4961] [Feature] Support header and OpenID Connect authentication in API client #79539

New Issue
Closed
opened 2026-05-19 02:30:07 -05:00 by GiteaMirror · 4 comments
GiteaMirror commented 2026-05-19 02:30:07 -05:00
Owner
Copy Link

Originally created by @latetedemelon on GitHub (May 8, 2025).
Original GitHub issue: https://github.com/actualbudget/actual/issues/4961

Verified feature request does not already exist?

  • I have searched and found no existing issue

💻

  • Would you like to implement this feature?

Pitch: what problem are you trying to solve?

The official @actual-app/api client currently only supports password-based authentication through a password parameter in api.init() and does not expose any mechanism to leverage server-side header-based (x-actual-password) or OpenID Connect flows for non-interactive authentication.

While the Actual Server supports multiple login methods including header auth and an experimental OpenID Connect provider integration the client library does not allow API consumers to configure or use these alternative auth methods, forcing scripts to rely on embedding server passwords and preventing the use of SSO or API tokens in headless workflows.

Describe your ideal solution to this problem

Add an authMethod option to api.init() (Node.js) and with allowed values password | header | openid, mirroring the server’s loginMethod and allowedLoginMethods settings. Ideally we'd be able to support different methods via the API vs. the UI at the same time.

Header mode: accept a long-lived API token or header secret and send it as x-actual-password on every request, eliminating reliance on the password form.

OpenID mode: implement a non-interactive OAuth2/OIDC client-credentials or device-flow to obtain and refresh bearer tokens for scripting contexts, leveraging the OpenID Connect provider feature.

Teaching and learning

Documentation: Update the “Using the API” docs with clear examples for each authMethod, including sample code snippets.

Migration guide: Provide a guide showing how to switch existing scripts from password to header or OpenID modes.

Testing: Add automated tests covering password, header, and OpenID authentication flows against a test server configured for each method.

Discoverability: Add an “Authentication Methods” section to the README, and link prominently in the API docs, so users immediately see alternate auth options.

Originally created by @latetedemelon on GitHub (May 8, 2025). Original GitHub issue: https://github.com/actualbudget/actual/issues/4961 ### Verified feature request does not already exist? - [x] I have searched and found no existing issue ### 💻 - [ ] Would you like to implement this feature? ### Pitch: what problem are you trying to solve? The official @actual-app/api client currently only supports password-based authentication through a password parameter in api.init() and does not expose any mechanism to leverage server-side header-based (x-actual-password) or OpenID Connect flows for non-interactive authentication. While the Actual Server supports multiple login methods including header auth and an experimental OpenID Connect provider integration the client library does not allow API consumers to configure or use these alternative auth methods, forcing scripts to rely on embedding server passwords and preventing the use of SSO or API tokens in headless workflows. ### Describe your ideal solution to this problem Add an authMethod option to api.init() (Node.js) and with allowed values password | header | openid, mirroring the server’s loginMethod and allowedLoginMethods settings. Ideally we'd be able to support different methods via the API vs. the UI at the same time. Header mode: accept a long-lived API token or header secret and send it as x-actual-password on every request, eliminating reliance on the password form. OpenID mode: implement a non-interactive OAuth2/OIDC client-credentials or device-flow to obtain and refresh bearer tokens for scripting contexts, leveraging the OpenID Connect provider feature. ### Teaching and learning Documentation: Update the “Using the API” docs with clear examples for each authMethod, including sample code snippets. Migration guide: Provide a guide showing how to switch existing scripts from password to header or OpenID modes. Testing: Add automated tests covering password, header, and OpenID authentication flows against a test server configured for each method. Discoverability: Add an “Authentication Methods” section to the README, and link prominently in the API docs, so users immediately see alternate auth options.
GiteaMirror added the featureneeds votes labels 2026-05-19 02:30:07 -05:00
GiteaMirror commented 2026-05-19 02:30:10 -05:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (May 8, 2025):

✨ Thanks for sharing your idea! ✨

This repository uses lodash style issue management for enhancements. That means enhancement issues are automatically closed. This doesn’t mean we don’t accept feature requests, though! We will consider implementing ones that receive many upvotes, and we welcome contributions for any feature requests marked as needing votes (just post a comment first so we can help you make a successful contribution).

The enhancement backlog can be found here: https://github.com/actualbudget/actual/issues?q=label%3A%22needs+votes%22+sort%3Areactions-%2B1-desc+

Don’t forget to upvote the top comment with 👍!

<!-- gh-comment-id:2864121394 --> @github-actions[bot] commented on GitHub (May 8, 2025): :sparkles: Thanks for sharing your idea! :sparkles: This repository uses lodash style issue management for enhancements. That means enhancement issues are automatically closed. This doesn’t mean we don’t accept feature requests, though! We will consider implementing ones that receive many upvotes, and we welcome contributions for any feature requests marked as needing votes (just post a comment first so we can help you make a successful contribution). The enhancement backlog can be found here: https://github.com/actualbudget/actual/issues?q=label%3A%22needs+votes%22+sort%3Areactions-%2B1-desc+ Don’t forget to upvote the top comment with 👍! <!-- feature-auto-close-comment -->
GiteaMirror commented 2026-05-19 02:30:11 -05:00
Author
Owner
Copy Link

@Ovyerus commented on GitHub (Aug 5, 2025):

+1, would love to be able to write a thing to integrate my bank with Actual to create transactions automatically, but I'm also using OIDC.

Rather than needing the API package to know OIDC stuff, I think just letting users generate an API key to put in the password option (or a different name if that's not possible, not sure of how it works internally) would be simpler and best, and would also open it up to creating API keys with certain permissions (e.g. read-only, scoped to certain accounts) later on if wanted.

<!-- gh-comment-id:3155582126 --> @Ovyerus commented on GitHub (Aug 5, 2025): +1, would love to be able to write a thing to integrate my bank with Actual to create transactions automatically, but I'm also using OIDC. Rather than needing the API package to know OIDC stuff, I think just letting users generate an API key to put in the password option (or a different name if that's not possible, not sure of how it works internally) would be simpler and best, and would also open it up to creating API keys with certain permissions (e.g. read-only, scoped to certain accounts) later on if wanted.
GiteaMirror commented 2026-05-19 02:30:11 -05:00
Author
Owner
Copy Link

@bertmelis commented on GitHub (Sep 5, 2025):

I haven't tried it, but can you currently use password based logins for your external applications while using OIDC as a user?

<!-- gh-comment-id:3257180197 --> @bertmelis commented on GitHub (Sep 5, 2025): I haven't tried it, but can you currently use password based logins for your external applications while using OIDC as a user?
GiteaMirror commented 2026-05-19 02:30:12 -05:00
Author
Owner
Copy Link

@tscibilia commented on GitHub (Sep 8, 2025):

Confirmed this works with both password and OIDC enabled, from what I understand, just don't enforce OIDC and allow for both login methods. I got some guidance from... https://github.com/seriouslag/actual-auto-sync/issues/8

<!-- gh-comment-id:3266524422 --> @tscibilia commented on GitHub (Sep 8, 2025): Confirmed this works with both password and OIDC enabled, from what I understand, just don't enforce OIDC and allow for both login methods. I got some guidance from... https://github.com/seriouslag/actual-auto-sync/issues/8
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
AI generated
API
bank sync
budgeting
bug
can’t replicate
dependencies
docker
documentation
electron
experimental feature
feature
feedback
goal templates
good first issue
help wanted
importers
maintenance
needs info
needs testing
needs triage
needs votes
openid
payees
pull-request
Mirrored from GitHub Pull Request
 regression
reports
responsive
rules
schedules
server
✨ merged
split transactions
tech debt
tech-support
theme
transaction import
transaction reconciliation
transactions
translations
upstream
user interface
✅ approved
wontfix
No Label feature needs votes
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
GiteaMirror ninjasurge
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: github-starred/actual#79539
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?