To generate an OAuth2 token, you’ll need to specify scopes that enable the token to use a specific set of API endpoints. This guide provides the complete list of scopes and guidance for using them.

Account-restricted scopes

Some scopes are not restricted to a single account:

  • / lets you call GET /ping to make sure the API is responding.
  • /accounts.write lets you call POST /accounts to create a new connected 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}/ 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, then you can generate a single OAuth token with a space-delimited list of the required scopes.

Suppose you need to read an account’s profile for display, update some of its properties, and then create a transfer. You’ll generate a single OAuth token with these scopes:

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

If you don’t yet have an account ID or have a more complex task to accomplish, then you’ll need to generate more than one OAuth token.

Suppose you’re trying to accomplish the same set of tasks above, but you need to create the account first. You’ll generate two OAuth tokens with these scopes:

  • 1st token
    • /accounts.write
  • 2nd token
    • /accounts/{accountID}/
    • /accounts/{accountID}/profile.write
    • /accounts/{accountID}/transfers.write

You’ll use the 1st token to call POST /account, which will return the ID of the new account. You’ll use that ID to construct the scopes for the 2nd token.

Available scopes

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