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

You’ll set scopes to 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:

  • / 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:

  • First token
    • /accounts.write
  • Second token
    • /accounts/{accountID}/
    • /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. You’ll use that ID to construct the scopes for the second token.

Available scopes

The accountID for transfers related scopes should be the facilitator’s account ID. The accountID for all other scopes will be the connected accountID.
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}/, /accounts/{accountID}/files.write Access to view or upload files 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