# 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.

![](https://fast.wistia.com/embed/medias/erk98x51xc/swatch)

## [Account-restricted scopes](#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](#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 you 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](#available-scopes)

The account ID for transfer-related scopes should be the **platform** account ID. The account ID for all other scopes will be the **user's** account ID.

| 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 card 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                                                                    |
| `/accounts/{accountID}/wallets.write`                                                       | Access to manage an account's Moov wallet                                                                                 |
| `/accounts/{accountID}/apple-pay.write`                                                     | Allows a developer to add or remove an Apple Pay domain                                                                   |
| `/accounts/{accountID}/apple-pay.read`                                                      | Allows a developer to retrieve registered Apple Pay domains                                                               |
| `/card-metadata.read`                                                                       | Allows look up of card metadata without linking it to a Moov account. Requires Moov PCI attestation of compliance to use. |
| `/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                                        |