Access Tokens
The Access Tokens page contains the following main sections:
- Add Access Token
- Refresh To Access Token
- Access Tokens List
The bottom section of the page is where you can view all the access tokens that are currently stored in the GrapSpy database. Anytime GraphSpy obtains an access token through any means, it will store it in its database. For example:
- Using a refresh token to create a new access token
- Manually adding an access token
- Using the device code flow
Every time a new access token is stored, a unique incremental ID is automatically assigned to it. This ID acts as the primary key to interact with these access tokens.
If you want to copy the raw access token to your clipboard, you can click on the copy icon. To permanently delete an access token, the delete button can be used.
GraphSpy also allows you to view the full decoded access token by using the dropdown arrow.
If you want to use an access token through GraphSpy, you will have to set it as the "Active Access Token". Whenever GraphSpy performs an action that would require authentication, it will use the currently active access token to authenticate to the resource.
There are multiple ways to set the active access token:
- From the Access Tokens List on the Access Tokens page, click on the checkmark icon (✓) to activate a specific access token
- On the Access Tokens page, enter the ID of the access token you wish to activate and click the
Set active tokenbutton - From the
Token OptionsSide Bar on any page, fill in the ID of the access token you wish to activate and click theSet active access tokenbutton
The last option will usually be the most convenient if you quickly want to switch the active access token without switching to the Access Token page.
The sidebar will also show a quick summary of your current access token. If your access token is expired, the background of the token summary will be red as shown in the following image.
If you quickly want to refresh your current access token with the exact same resource and client id, you can simply click the Refresh and activate button at the top. This will request a new access token with your current active refresh token, and will automatically activate the new access token.
By default, the Resource and Client ID are set to the values of your current access token, however, you can easily change these parameters as well to request an access token for a different Resource and/or Client ID.
The background of the access token summary will be green if it has not expired yet. (Note: The color is just an indication and is determined by comparing the current time with the expiry time. It will not actually verify whether the token is still valid.)
When using access tokens in GraphSpy, there are two things you need to look at to determine what you can do with it:
- Resource
- Scope
The resource needs to match the specific API which is used. For instance, if you want to use a feature that interacts with the Microsoft Graph API in the background, you will need an access token for the resource https://graph.microsoft.com.
Secondly, the Scope is also important as this actually defines which privileges you have over specific types of objects. For instance, if you want to view the files in the user's OneDrive, you will require one of the following scopes: Files.Read, Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, ...
While you can't directly control which scopes you get in most cases (because Microsoft ignores whatever scopes you request), you can still indirectly influence what kind of scope you are going to receive. In fact, Microsoft seems to look at the Client ID in the access token request, and will automatically set the required scopes which Microsoft believes are required for that specific type of client.
For instance, when you request an access token for the Microsoft Graph API resource with the Client ID of Microsoft Teams, you will always receive the following scope:
AppCatalog.Read.All Channel.ReadBasic.All Contacts.ReadWrite.Shared Files.ReadWrite.All InformationProtectionPolicy.Read MailboxSettings.ReadWrite Notes.ReadWrite.All People.Read Place.Read.All Sites.ReadWrite.All Tasks.ReadWrite Team.ReadBasic.All TeamsAppInstallation.ReadForTeam TeamsTab.Create User.ReadBasic.All
If you want to list which SharePoint sites exist, you will require either Sites.Read.All or Sites.ReadWrite.All according to the documentation. As we can see, we can receive the Sites.ReadWrite.All scope from the Microsoft Teams Client ID. This scope is not available when using the Microsoft Office Client ID for instance, so the SharePoint Sites tab will not work with such an access token.
The following table provides a brief overview of what resources and scopes are required for which specific page. (You only need one of the scopes listed in the scopes column, not all of them.
| Page | Resource | Scope |
|---|---|---|
| Generic Graph Requests | https://graph.microsoft.com | Depends on the API used. Refer to the Microsoft documentation. |
| Generic Search | https://graph.microsoft.com | Depends on the entity type you want to search. A full list can be found here |
| Recent Files | https://graph.microsoft.com | Files.Read, Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
| Files Shared With Me | https://graph.microsoft.com | Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
| OneDrive | https://graph.microsoft.com | Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
| SharePoint Sites | https://graph.microsoft.com | Sites.Read.All, Sites.ReadWrite.All |
| SharePoint Drives | https://graph.microsoft.com | Files.Read, Files.Read.All, Files.ReadWrite, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
| SharePoint Files | https://graph.microsoft.com | Files.Read, Files.ReadWrite, Files.Read.All, Files.ReadWrite.All, Sites.Read.All, Sites.ReadWrite.All |
| Outlook | https://outlook.office365.com | * |
Most functionality in GraphSpy is built to interact with the Microsoft Graph API. As such, you will usually want to utilize access tokens for the resource https://graph.microsoft.com.