Skip to main content
POST
/
v1
/
identity
/
sessions
Create Auth Session
curl --request POST \
  --url https://api.example.com/v1/identity/sessions \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "<string>",
  "provider": "<string>"
}
'
{
  "session_id": "<string>",
  "auth_url": "<string>",
  "expires_at": "<string>"
}

​
Create Auth Session

Create a just-in-time (JIT) authentication session. This returns a URL to redirect the user to for OAuth authorization.

​
Request

curl -X POST https://api.mcprank.com/v1/identity/sessions \
  -H "X-API-Key: sk_mcp_rank_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "provider": "google"
  }'

​
Body Parameters

​
user_id
string
required
Your user’s unique identifier
​
provider
string
required
OAuth provider to authenticate with. Currently supported: google

​
Response

​
session_id
string
Unique identifier for this auth session - use for polling status
​
auth_url
string
URL to redirect the user to for OAuth authorization
​
expires_at
string
ISO timestamp when this session expires (typically 5 minutes)

​
Example Response

{
  "session_id": "sess_abc123",
  "auth_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=...&scope=...",
  "expires_at": "2024-01-15T10:05:00Z"
}

​
Flow

  1. Call this endpoint to get an auth_url
  2. Redirect user to auth_url (or open in popup/new tab)
  3. User authorizes in Google
  4. Google redirects to MCP Rank’s callback
  5. MCP Rank stores tokens server-side
  6. Poll /v1/identity/sessions/{session_id} for completion
  7. Once complete, proxy requests will work

​
Example Flow

# 1. Create session
session = await client.create_auth_session("google")

# 2. Show URL to user
print(f"Please open: {session['auth_url']}")

# 3. Poll for completion
import asyncio
while True:
    status = await client.check_session_status(session["session_id"])
    if status["status"] == "complete":
        print("Success!")
        break
    elif status["status"] == "error":
        raise Exception(f"Auth failed: {status['error']}")
    await asyncio.sleep(1)

# 4. Refresh client and make requests
await client.initialize()
profile = await client.proxy_get("google", "gmail/v1/users/me/profile")

​
Notes

  • Sessions expire after 5 minutes
  • After successful auth, tokens are stored server-side (KMS encrypted)
  • The same user_id can have multiple providers connected