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

# Get Session Status

> Poll the status of an auth session

# Get Session Status

Poll the status of a JIT authentication session. Use this to know when the user has completed OAuth authorization.

## Request

```bash theme={null}
curl https://api.mcprank.com/v1/identity/sessions/sess_abc123 \
  -H "X-API-Key: sk_mcp_rank_..."
```

### Path Parameters

<ParamField path="session_id" type="string" required>
  The session ID returned from Create Auth Session
</ParamField>

## Response

<ResponseField name="status" type="string">
  Session status: `pending`, `complete`, or `error`
</ResponseField>

<ResponseField name="error" type="string">
  Error message if status is `error`
</ResponseField>

### Status Values

| Status     | Meaning                                                 |
| ---------- | ------------------------------------------------------- |
| `pending`  | User hasn't completed auth yet - keep polling           |
| `complete` | Auth successful - tokens stored, ready to make requests |
| `error`    | Auth failed - check `error` field for details           |

### Example Responses

**Pending:**

```json theme={null}
{
  "status": "pending"
}
```

**Complete:**

```json theme={null}
{
  "status": "complete"
}
```

**Error:**

```json theme={null}
{
  "status": "error",
  "error": "User denied access"
}
```

## Polling Example

```python theme={null}
import asyncio

async def wait_for_auth(client, session_id, timeout=300):
    """Poll until auth completes or times out."""
    elapsed = 0
    while elapsed < timeout:
        status = await client.check_session_status(session_id)
        
        if status["status"] == "complete":
            return True
        elif status["status"] == "error":
            raise Exception(f"Auth failed: {status.get('error')}")
        
        await asyncio.sleep(1)
        elapsed += 1
    
    raise Exception("Auth timed out")
```

## Notes

* Poll every 1-2 seconds
* Sessions expire after 5 minutes
* Once `complete`, you should call `initialize()` to refresh the client's MIT
* The session ID is single-use - don't poll after receiving `complete` or `error`