Authentication

Yolocode authenticates users via GitHub. Every API request requires a valid GitHub token passed as a Bearer token in the Authorization header.

Auth flow

Authorization: Bearer <github_token_ghp_...>

The API validates your token by calling GET https://api.github.com/user. If valid, it extracts your userId and login for access control.

Getting a token

OAuth flow

For web and mobile apps, use the standard GitHub OAuth flow:

1. Redirect users to GitHub authorization
2. GitHub redirects back to https://api.yolocode.ai/api/auth/callback with a code
3. Exchange the code for a token via POST /api/github/oauth/token

The callback handler supports multiple origins:

• Mobile: myapp:// deep links
• Expo: exp:// links
• Web: Validated against allowed origins

Device flow

For CLI and headless environments:

# Step 1: Request a device code
curl -X POST https://api.yolocode.ai/api/github/device/code \
  -H "Content-Type: application/json" \
  -d '{"scope": "user repo read:org workflow"}'

# Step 2: User visits the verification URL and enters the code

# Step 3: Poll for the access token
curl -X POST https://api.yolocode.ai/api/github/device/token \
  -H "Content-Type: application/json" \
  -d '{"device_code": "<device_code>"}'

Sandbox auth

Sandboxes use JWT tokens for internal authentication. When you create a sandbox, a JWT is generated with:

• Algorithm: HS256
• Issuer: yolocode-api
• Expiry: 24 hours
• Payload: userId, sandbox name

These JWTs are used internally by the Claude Gateway to validate requests from within sandboxes. Do not use them for API requests.

Payment gating

Some features (like the Claude Gateway) require a paid account. The API checks your payment status via WorkOS user metadata. If you haven't paid, the Claude Gateway returns 402 Payment Required.

Troubleshooting