Playtest Parlor

Playtest Parlor uses OAuth2 to authenticate API requests. Users authorize your app once, and you receive a long-lived token to make API calls on their behalf.

Register Your App

Before you can authenticate users, register your application:

Go to Settings > Developer Apps
Click "Create New Application"
Enter your app name and redirect URI (where you want users returned after approval)
Submit to receive your client_id

Authorization Flow

Step 1: Redirect User to Authorize Page

Build this URL and redirect your user to it:

https://playtestparlor.com/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&state=STATE

Parameters:

client_id (required): Your app's client ID from the developer portal
redirect_uri (required): Must match exactly the redirect URI registered for your app
state (recommended): An opaque string you generate to prevent CSRF attacks. Playtest Parlor will return it unchanged; verify it matches your original value

Step 2: User Approves

The user sees a page asking them to approve access. If they approve, their browser redirects to your redirect_uri with these parameters:

https://your-app.example.com/callback?code=AUTH_CODE&state=STATE

If they deny, they are returned without a code.

Step 3: Exchange Code for Token

On your server, make this POST request:

curl -X POST https://playtestparlor.com/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "code": "AUTH_CODE",
    "redirect_uri": "YOUR_REDIRECT_URI"
  }'

Request Body:

Field	Type	Description
`client_id`	string	Your app's client ID
`code`	string	The authorization code from step 2
`redirect_uri`	string	Must match the registered redirect URI and the one used in step 1

Response:

{
  "token": "pp_1a2b3c4d5e6f7g8h",
  "token_type": "bearer",
  "expires_in": null
}

The token is a long-lived bearer token. Store it securely (encrypted in a database). The expires_in field is currently null; your token is valid until the user revokes it.

Errors:

INVALID_CODE: The code is invalid or has expired (valid for 10 minutes)
CODE_EXPIRED: The authorization code has expired
REDIRECT_URI_MISMATCH: The redirect_uri doesn't match the registered value
CLIENT_ID_MISMATCH: The client_id is invalid or doesn't match the code

Using Your Token

Include the token in the Authorization header for all API requests:

curl -X GET https://playtestparlor.com/api/v1/games \
  -H "Authorization: Bearer pp_1a2b3c4d5e6f7g8h"

Tokens are long-lived and do not expire automatically. Users can revoke tokens from their account Settings at any time. If a request returns a 401 UNAUTHORIZED error, the token may have been revoked; prompt the user to authorize again.

Token Security

Store tokens encrypted in your database
Never expose tokens in logs, error messages, or client-side code
Transmit tokens only over HTTPS
Treat tokens with the same care as passwords

Rate Limits

Token exchange requests are rate limited to 5 per minute per user. See Errors for all rate limits.

Authentication