# Scopes and Roles

A Transact API access token authorises you to make requests in a limited capacity, the extent being dependent on:

- the Resource Owner's **role**, which is what kind of user they are (firm, network, investment manager)
- the access token's **scopes**, which are the permissions the Resource Owner has granted to your application.

Each Transact API endpoint has its own scope and role requirements, documented for each endpoint under _Authorisation Requirements_.

## Scopes

Transact's OAuth scopes grant access to a specific resource or business area. When the Resource Owner is asked to grant access
as part of the OAuth flow, a clear description of each requested [scope](#current-scopes) is displayed to them.

### Read-only scopes

In many cases, the Resource Owner may not be comfortable with granting your application full access
(i.e. read and write). For example, it is much higher risk for the user to allow an application to create transactions
than it is to allow an application to read them.

To support this use case, scopes can be made read-only by adding the `.read` suffix. For example, a
theoretical `transaction` scope would give permission to create, read, update, and delete transactions, while a
`transaction.read` scope would only bestow the permission to read transactions.

:::info

You can only acquire scopes that are currently required by an endpoint.

This is a security measure to protect users from inadvertently granting permissions that your application does not need.

:::

## Roles

Transact API access is only available for use by certain types of Resource Owner. In the API context, the type of a
Resource Owner is known as their role. Currently, the Transact API supports Resource Owners with the following roles:

- Adviser firm (`FIRM`)
- Adviser network (`NETWORK`)
- Investment manager (`INVESTMENT_MANAGER`)

Most endpoints are only accessible for certain roles. For example, requests on behalf of Adviser network users
will receive a `403 Forbidden` response when attempting to access the [Prepopulate a Personalised Illustration](/api/account-opening#prepopulate-a-personalised-illustration)
endpoint, as that functionality is only available to firms.

## Current scopes

Here are the scopes that Transact API supports, along with the roles that are permitted to grant access:

| Scope                           | Description (shown to Resource Owner)                                                                                                | Supported Roles                         |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `investor-personal.read`        | View clients' personal data and contact information                                                                                  | `FIRM`, `NETWORK`                       |
| `investor-illustration-profile` | View, add, edit, delete temporary client profiles for use within illustrations/applications                                          | `FIRM`                                  |
| `transaction.read`              | View client transactions                                                                                                             | `FIRM`, `NETWORK`                       |
| `valuation.read`                | View client valuations                                                                                                               | `FIRM`, `NETWORK`                       |
| `entity.read`                   | View basic wrapper, client, adviser, firm, investment manager information (excluding clients' personal data and contact information) | `FIRM`, `NETWORK`, `INVESTMENT_MANAGER` |
| `metadata.read`                 | View Transact's available investments, ceding parties and other common platform data                                                 | `FIRM`, `NETWORK`, `INVESTMENT_MANAGER` |

:::info

All tokens are implicitly granted the `metadata.read` scope - there is no need to explicitly request it.

:::

:::warning

There are some deprecated [Transact Remote Data Service](../guides/migrating-from-trds.md) endpoints that require the following scopes:

- `Read`: Read your client data
- `Stage`: Send data for your use within Transact Online

These are not usable with the Transact API and are slated for removal.

:::

## Reading a token's scope and role

Your application can decode and read access tokens to confirm the token's scope, the Resource Owner's role, and other
metadata. For more information, see [Token Claims](tokens.md).