OAuth 2.0 Flows

Learn how to implement OAuth 2.0 authentication flows with the Propper Auth API.

Client Credentials Flow

Best for server-to-server authentication where no user interaction is needed.

When to Use

• Backend services calling Propper APIs
• Automated processes and cron jobs
• Service-to-service communication

Implementation

curl -X POST "https://auth.propper.ai/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=sign:read sign:write"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "sign:read sign:write"
}

Using the Token

Include the access token in the Authorization header:

curl "https://api.propper.ai/v1/sign/documents" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Authorization Code Flow with PKCE

Best for web applications and mobile apps where user authentication is required.

When to Use

• Web applications with user login
• Mobile applications
• Single-page applications (SPAs)

Step 1: Generate PKCE Challenge

// Generate code verifier (random string)
const codeVerifier = generateRandomString(64);

// Generate code challenge (SHA-256 hash, base64url encoded)
const codeChallenge = base64url(sha256(codeVerifier));

Step 2: Redirect to Authorization

https://auth.propper.ai/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=openid profile sign:read&
  state=random_state_value&
  code_challenge=YOUR_CODE_CHALLENGE&
  code_challenge_method=S256

Step 3: Exchange Code for Tokens

After user authenticates, they're redirected to your callback URL with an authorization code:

curl -X POST "https://auth.propper.ai/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile sign:read"
}

Available Scopes

Scope	Description
openid	Required for OIDC, returns ID token
profile	Access to user profile information
email	Access to user email
sign:read	Read access to Sign API
sign:write	Write access to Sign API
click:read	Read access to Click API
click:write	Write access to Click API

Security Best Practices

1. Always use PKCE for public clients (SPAs, mobile apps)
2. Store tokens securely - never in localStorage for sensitive apps
3. Validate tokens on your backend before trusting claims
4. Use short-lived access tokens and refresh as needed
5. Implement token rotation for refresh tokens