Authentication

Parkdly uses the OAuth 2.0 Authorization Code Flow with PKCE. An application can access user data only when the user gives consent.

OAuth 2.0 Flow Overview

The authentication process has four steps:

Authorization Request - Send the user to Parkdly for consent
Token Exchange - Exchange the authorization code for access tokens
API Requests - Use the access token to call API endpoints
Token Refresh - Get a new access token when the old one expires

Step 1: Authorization Request

Send the user to the authorization endpoint. There, the user gives your application access.

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

Parkdly sends the user back to your redirect_uri with: ?code={code}&state={state}

Step 2: Token Exchange

Exchange the authorization code for an access token and a refresh token.

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

An access token expires 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

To check if an access token is valid, send POST /oauth/introspect.

Use Basic Auth with your client credentials. Send the token parameter. The response has active: true or active: false. If the token is active, the response also has token metadata.

PKCE Implementation

We strongly recommend PKCE (Proof Key for Code Exchange). It prevents attackers from using an authorization code that they intercepted.

Flow:

Generate a random code_verifier (43-128 chars, base64url encoded).
Make a SHA-256 hash of it. This is the code_challenge.
Send code_challenge and code_challenge_method=S256 in the authorization request.
Send the same code_verifier in the token exchange.

Best Practices

✅ Always use PKCE.
✅ Validate the state parameter to prevent CSRF attacks.
✅ Store tokens securely. Do not put them in logs or client-side code.
✅ Refresh tokens before they expire.
✅ Handle token revocation. Your application can receive 401 errors.
✅ Use HTTPS for all OAuth flows.

Next Steps

API Endpoints - Make API calls
Webhooks - Receive notifications
Error Handling - Handle OAuth errors