auth_status - Tiro Docs

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

{}

Response Format

Success Response

{
  "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:

// 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

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

Best Practices

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.

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.

​Overview

​Parameters

​Request Example

​Response Format

​Success Response

​Understanding Scopes

​Usage Examples

​Debugging Permission Errors

​Verifying API Key Kind

​Common Errors

​Invalid or Expired Credentials

​Best Practices