Documentation

Quick Start

1. Create an API key

   curl -X POST https://inbox.dog/api/keys   -H "Content-Type: application/json"   -d '{"name": "my-app"}'

2. Redirect users to authenticate

   https://inbox.dog/oauth/authorize?
     client_id=YOUR_CLIENT_ID&
     redirect_uri=https://yourapp.com/callback&
     scope=email

3. Exchange code for tokens

   curl -X POST https://inbox.dog/oauth/token   -H "Content-Type: application/json"   -d '{
       "code": "AUTH_CODE",
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET"
     }'

API Keys

Create an API key to get your client_id and client_secret.

Create Key

POST /api/keys
Content-Type: application/json

{"name": "my-app"}

Response:

{
  "client_id": "id_abc123...",
  "client_secret": "sk_xyz789...",
  "name": "my-app",
  "credits": 10
}

Check Key Info

GET /api/keys/{client_id}
X-Client-Secret: YOUR_CLIENT_SECRET

OAuth Flow

Standard OAuth 2.0 authorization code flow:

1. Redirect user to /oauth/authorize
2. User authenticates with Google
3. User is redirected back to your redirect_uri with a code
4. Exchange code for tokens at /oauth/token

Authorization Request

GET /oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=email&
  state=random_state_value

Token Exchange

Exchange the authorization code for access tokens:

POST /oauth/token
Content-Type: application/json

{
  "code": "AUTH_CODE_FROM_CALLBACK",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Response:

{
  "access_token": "ya29.a0AfH6...",
  "refresh_token": "1//0eXyz...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "email": "user@example.com"
}

Refresh Tokens

Use the refresh token to get new access tokens:

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET"
}

Scopes

Billing

Each OAuth token exchange costs 1 credit. New API keys come with 10 free credits.

Purchase more credits:

POST /api/checkout
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "credits": 100
}

Returns a Stripe checkout URL. Price: $0.10 per credit.