Scopes
Overview
Moov’s authentication flow follows the OAuth2 protocol. 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. 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:
/ping.read: lets you callGET /pingto make sure the API is responding/accounts.write: lets you callPOST /accountsto 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 callPUT /accounts/{accountID}to update that account’s profile, metadata, or other properties/accounts/{accountID}/wallets.read: lets you callGET /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}/profile.read/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}/profile.read/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
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, /accounts.read |
Allows a new Moov account to be created, and view all connected 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 |