> ## 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.

# Create Auth Session

> Create a JIT authentication session for OAuth

# Create Auth Session

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

## Request

```bash theme={null}
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

<ParamField body="user_id" type="string" required>
  Your user's unique identifier
</ParamField>

<ParamField body="provider" type="string" required>
  OAuth provider to authenticate with. Currently supported: `google`
</ParamField>

## Response

<ResponseField name="session_id" type="string">
  Unique identifier for this auth session - use for polling status
</ResponseField>

<ResponseField name="auth_url" type="string">
  URL to redirect the user to for OAuth authorization
</ResponseField>

<ResponseField name="expires_at" type="string">
  ISO timestamp when this session expires (typically 5 minutes)
</ResponseField>

### Example Response

```json theme={null}
{
  "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

```python theme={null}
# 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