Authentication

Parkdly uses OAuth 2.0 Authorization Code Flow with PKCE support for secure authentication. This industry-standard approach ensures that only authorized applications can access user data with explicit user consent.

OAuth 2.0 Flow Overview

The authentication process follows these steps:

Authorization Request - Redirect users to Parkdly for consent
Token Exchange - Exchange authorization code for access tokens
API Requests - Use access token to call API endpoints
Token Refresh - Renew expired access tokens

Step 1: Authorization Request

Redirect users to the authorization endpoint to grant access to your application.

Endpoint

GET /oauth/authorize

Parameters

Parameter	Required	Description
`client_id`	Yes	Your application's client ID
`redirect_uri`	Yes	Registered callback URL
`response_type`	Yes	Must be `code`
`state`	Recommended	Random string to prevent CSRF attacks
`code_challenge`	Recommended	PKCE code challenge (base64url, 43-128 chars)
`code_challenge_method`	If PKCE	`S256` or `plain` (S256 recommended)

Example

https://parkdly.com/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&state={state}&code_challenge={challenge}&code_challenge_method=S256

User is redirected back with: ?code={code}&state={state}

Step 2: Token Exchange

Exchange the authorization code for access and refresh tokens.

Endpoint

POST /oauth/token

Headers

Content-Type: application/x-www-form-urlencoded

Parameters (form-encoded)

Parameter	Required	Description
`grant_type`	Yes	`authorization_code` or `refresh_token`
`client_id`	Yes	Your application's client ID
`client_secret`	Yes	Your application's client secret
`code`	If authorization_code	The authorization code
`redirect_uri`	If authorization_code	Must match the authorization request
`code_verifier`	If PKCE used	Original random string (43-128 chars)
`refresh_token`	If refresh_token	The refresh token

Example

curl -X POST https://parkdly.com/oauth/token \
  -d "grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&code={code}&redirect_uri={redirect_uri}&code_verifier={verifier}"

Returns access_token, refresh_token, and expires_in.

Step 3: Refresh Access Token

Access tokens expire after 1 hour. Use the refresh token to get a new access token.

curl -X POST https://parkdly.com/oauth/token \
  -d "grant_type=refresh_token&client_id={client_id}&client_secret={client_secret}&refresh_token={refresh_token}"

Token Introspection

Verify an access token's validity: POST /oauth/introspect

Use Basic Auth with your client credentials and send token parameter. Returns active: true/false with token metadata if active.

PKCE Implementation

PKCE (Proof Key for Code Exchange) is strongly recommended to prevent authorization code interception attacks.

Flow:

Generate random code_verifier (43-128 chars, base64url encoded)
Create SHA-256 hash → code_challenge
Send code_challenge + code_challenge_method=S256 in authorization request
Send original code_verifier in token exchange

Best Practices

✅ Always use PKCE for enhanced security
✅ Validate state parameter to prevent CSRF attacks
✅ Store tokens securely - never expose in logs or client-side code
✅ Refresh tokens proactively before they expire
✅ Handle token revocation - be prepared for 401 errors
✅ Use HTTPS only for all OAuth flows

Next Steps

API Endpoints - Start making API calls
Webhooks - Set up real-time notifications
Error Handling - Handle OAuth errors properly