REST Integration Playbook

1) Create an OAuth2 client -> 2) Generate PKCE + state -> 3) Send user to `/oauth2/authorize` -> 4) Exchange code at `/oauth2/token` -> 5) Store `access_token` + `refresh_token` -> 6) Call `/oauth2/v1/*` with Bearer token.

1) Get a Client ID

Register your app and obtain client_id (and optional client_secret) from the Developer Dashboard or via REST.

POST /api/v1/oauth2/clients
Content-Type: application/json

{
  "clientName": "My Flutter App",
  "redirectUri": "myapp://auth/callback",
  "requestedScopes": ["api:access", "profile:read"]
}

2) Generate PKCE + State

Generate these per login:

• code_verifier: random 43-128 chars
• code_challenge: BASE64URL(SHA256(code_verifier))
• state: random string to prevent CSRF

const verifier = generateRandom(64);
const challenge = await sha256Base64Url(verifier);
const state = generateRandom(24);

final verifier = generateRandomString(64);
final challenge = base64UrlEncode(
  sha256.convert(utf8.encode(verifier)).bytes
).replaceAll('=', '');
final state = generateRandomString(24);

3) Launch the OAuth Screen

Open the user's browser (or url_launcher in Flutter) to:

GET https://aipass.one/oauth2/authorize
  ?client_id=YOUR_CLIENT_ID
  &response_type=code
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=api:access profile:read
  &state=STATE_VALUE
  &code_challenge=PKCE_CHALLENGE
  &code_challenge_method=S256

Use custom schemes like myapp://auth/callback on mobile. Validate the returned state before exchanging the code.

4) Exchange Code & Refresh

Exchange the authorization code

POST https://aipass.one/oauth2/token
Content-Type: application/json

{
  "grantType": "authorization_code",
  "code": "CODE_FROM_REDIRECT",
  "codeVerifier": "ORIGINAL_CODE_VERIFIER",
  "clientId": "YOUR_CLIENT_ID",
  "redirectUri": "YOUR_REDIRECT_URI"
}

Response fields: access_token, refresh_token, expires_in, token_type (Bearer), scope.

Refresh tokens

POST https://aipass.one/oauth2/token
Content-Type: application/json

{
  "grantType": "refresh_token",
  "refreshToken": "YOUR_REFRESH_TOKEN",
  "clientId": "YOUR_CLIENT_ID"
}

5) Call AI Pass Endpoints

Send the Bearer token in every request. The proxy mirrors OpenAI-style payloads and streams via SSE when stream: true.

Chat completion

curl -X POST https://aipass.one/oauth2/v1/chat/completions \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-4o-mini",
        "messages": [
          {"role":"system","content":"You answer briefly."},
          {"role":"user","content":"One tip for better focus?"}
        ],
        "max_tokens": 200,
        "stream": false
      }'

6) Vision API (Multimodal)

Same /oauth2/v1/chat/completions endpoint, but with multimodal content. Send text + images for analysis.

Structure: Image + Text

The content field accepts an array of parts instead of a string:

{
  "model": "gpt-4o-mini",
  "messages": [{
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "What's in this image?"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
        }
      }
    ]
  }],
  "max_tokens": 2000
}

7) Usage & Balance Tracking

Monitor your AI API costs and remaining budget in real-time.

GET https://aipass.one/api/v1/usage/me/summary
Authorization: Bearer ACCESS_TOKEN

// Response:
{
  "success": true,
  "message": "Usage summary retrieved successfully",
  "data": {
    "totalCost": 2.45,
    "maxBudget": 10.00,
    "remainingBudget": 7.55
  },
  "timestamp": "2024-01-15T14:30:00Z"
}

8) All REST Endpoints