> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# auth_status

> Check current authentication status and permissions

## Overview

`auth_status` returns information about the current authentication state, including the authentication method, user identity, and granted scopes. This tool requires no parameters and no specific scope.

**Primary Use Cases:**

* Verify that authentication is configured correctly
* Debug permission issues when other tools return authorization errors
* Confirm which scopes are available before making tool calls

**Key Features:**

* No parameters required
* No scope required
* Returns complete authentication context

***

## Parameters

This tool takes no parameters.

### Request Example

```json theme={"system"}
{}
```

***

## Response Format

### Success Response

```json theme={"system"}
{
  "authenticated": true,
  "authMethod": "api_key",
  "userId": 12345,
  "workspaceGuid": null,
  "clientId": "client_001",
  "scopes": [
    "mcp:notes:read",
    "mcp:folders:read"
  ]
}
```

**Field Descriptions:**

| Field           | Type           | Description                                            |
| --------------- | -------------- | ------------------------------------------------------ |
| `authenticated` | boolean        | Always `true` when this tool returns successfully      |
| `authMethod`    | string         | Authentication method used: `jwt` or `api_key`         |
| `userId`        | number \| null | The authenticated user's ID (set for user-scoped keys) |
| `workspaceGuid` | string \| null | The workspace GUID (set for workspace-scoped keys)     |
| `clientId`      | string         | The client application ID                              |
| `scopes`        | string\[]      | List of granted permission scopes                      |

***

## Understanding Scopes

The `scopes` array indicates which tools you have permission to use:

| Scope              | Grants Access To                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `mcp:notes:read`   | `list_notes`, `search_notes`, `get_note`, `get_note_transcript`, `list_document_templates`, `get_document_template`, `get_share_link` |
| `mcp:folders:read` | `search_private_folders`, `search_team_folders`                                                                                       |

***

## Usage Examples

### Debugging Permission Errors

If a tool call returns a `403 Forbidden` error, use `auth_status` to check your scopes:

```json theme={"system"}
// 1. Call auth_status
{}

// 2. Check the response
{
  "authenticated": true,
  "authMethod": "api_key",
  "userId": 12345,
  "workspaceGuid": null,
  "clientId": "client_001",
  "scopes": ["mcp:notes:read"]
}
```

In this example, the key only has `mcp:notes:read` scope. Tools requiring a different scope (e.g., `mcp:folders:read` for folder search) would return `403 Forbidden`.

### Verifying API Key Kind

Check `userId` and `workspaceGuid` to determine which kind of API key you are using:

* **User-scoped key:** `userId` is set; `workspaceGuid` is `null`. Can span multiple workspaces.
* **Workspace-scoped key:** `workspaceGuid` is set; `userId` is `null`. Tied to a single workspace, with no user identity.

***

## Common Errors

### Invalid or Expired Credentials

<Error>
  ```json theme={"system"}
  {
    "error": "Authentication failed. Invalid or expired credentials.",
    "code": "UNAUTHORIZED",
    "statusCode": 401
  }
  ```
</Error>

**Solution:** Verify your API key or JWT token is correct and has not expired. Generate a new key if needed.

***

## Best Practices

<AccordionGroup>
  <Accordion title="Call auth_status on Startup">
    When initializing your MCP client, call `auth_status` first to confirm connectivity and verify available scopes. This catches configuration issues early before making other tool calls.
  </Accordion>

  <Accordion title="Use for Troubleshooting">
    When a tool returns an unexpected authorization error, `auth_status` is the fastest way to diagnose the issue. Check whether the required scope is in the `scopes` array.
  </Accordion>
</AccordionGroup>