Skip to main content
GET
/
v1
/
identity
/
sessions
/
{session_id}
Get Session Status
curl --request GET \
  --url https://api.example.com/v1/identity/sessions/{session_id}
{
  "status": "<string>",
  "error": "<string>"
}

​
Get Session Status

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

​
Request

curl https://api.mcprank.com/v1/identity/sessions/sess_abc123 \
  -H "X-API-Key: sk_mcp_rank_..."

​
Path Parameters

​
session_id
string
required
The session ID returned from Create Auth Session

​
Response

​
status
string
Session status: pending, complete, or error
​
error
string
Error message if status is error

​
Status Values

StatusMeaning
pendingUser hasn’t completed auth yet - keep polling
completeAuth successful - tokens stored, ready to make requests
errorAuth failed - check error field for details

​
Example Responses

Pending: 
{
  "status": "pending"
}
Complete: 
{
  "status": "complete"
}
Error: 
{
  "status": "error",
  "error": "User denied access"
}

​
Polling Example

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