Ask Moov Beta
Generative AI is experimental and can make mistakes.
Guides Use cases API Changelog
  1. API reference
  2. Authentication

Scopes

Moov follows the OAuth2 protocol authentication flow. This guide provides the complete list of scopes and guidance for using them.

If you’re using Moov.js or any client-side integration, you’ll need to set scopes. Scopes specify what actions an account can take. When generating an OAuth2 access token, you’ll include the name of the scope that covers the type of access needed. You will then use a generated token for each API call you make.

Account-restricted scopes

Some scopes are not restricted to a single account:

  • /ping.read: lets you call GET /ping to make sure the API is responding
  • /accounts.write: lets you call POST /accounts to create a new user account

Other scopes are restricted to a single account, meaning you’ll need the account ID before you generate the token:

  • /accounts/{accountID}/profile.write: lets you call PUT /accounts/{accountID} to update that account’s profile, metadata, or other properties
  • /accounts/{accountID}/wallets.read: lets you call GET /accounts/{accountID}/wallets/{walletID} to see the balance in that wallet

Generating multiple tokens

If you already have an account ID and have a simple task to accomplish, you can generate a single OAuth token with a space-delimited list of the required scopes. For example, if you need to read an account’s profile for display, update some of its properties, and create a transfer, you’ll generate a single OAuth token with these scopes:

  • /accounts/{accountID}/profile.read
  • /accounts/{accountID}/profile.write
  • /accounts/{accountID}/transfers.write

If haven’t retrieved an account ID, or have a more complex task to accomplish, then you’ll need to generate more than one OAuth token. If you’re trying to accomplish the same set of tasks as above, but you need to create the account first, you’ll generate two OAuth tokens with these scopes:

  • First token
    • /accounts.write
  • Second token
    • /accounts/{accountID}/profile.read
    • /accounts/{accountID}/profile.write
    • /accounts/{accountID}/transfers.write

You’ll use the first token to call POST /account, which will return the ID of the new account. Use that account ID to construct the scopes for the second token.

Available scopes

The account ID for transfers related scopes should be the platform account ID. The account ID for all other scopes will be the user’s account ID.

If using the Node SDK, also see the scope enums section of the Node docs.

Scope Description
/accounts.write, /accounts.read Allows a new Moov account to be created, and view all connected user accounts
/accounts/{accountID}/bank-accounts.read, /accounts/{accountID}/bank-accounts.write Access to view or add a linked bank account to a Moov account
/accounts/{accountID}/cards.read, /accounts/{accountID}/cards.write Access to view or add a linked cards to a Moov account
/accounts/{accountID}/capabilities.read, /accounts/{accountID}/capabilities.write Access to request or view capabilities, determining what actions the account can do
/accounts/{accountID}/documents.read, /accounts/{accountID}/documents.write Access to view or upload documents (like I-9s, W-4s) associated with a Moov account
/accounts/{accountID}/files.read, /accounts/{accountID}/files.write Access to view or upload files associated with a Moov account
/accounts/{accountID}/payment-methods.read Access to view payment methods for the account specified
/accounts/{accountID}/profile-enrichment.read Access to view a Moov account’s profile image
/accounts/{accountID}/profile.read, /accounts/{accountID}/profile.write Access to view or edit details associated with a Moov account
/accounts/{accountID}/representatives.read, /accounts/{accountID}/representatives.write Access to view or add details on business representatives for a Moov account
/accounts/{accountID}/transfers.write, /accounts/{accountID}/transfers.read Access to move money by creating transfers
/accounts/{accountID}/wallets.read Access to view the balance on an account’s Moov wallet
/fed.read Allows a developer to use the institutions lookup service to look up a bank name by routing number
/ping.read Allows a developer to test and confirm they are able to hit one of Moov’s services
Summary Beta