Mobile quickstart

Register a public native app. Native applications cannot keep a client secret confidential, so use only the client ID and S256 PKCE.

Configure the callback

Register a callback such as dev.example.reader:/oauth/comick and configure your application's URL handler for that exact scheme and path. You can also register an HTTPS callback with your platform's verified app/universal-link association.

Authorize in the system browser

Use your platform's OAuth client library and system authentication browser. Generate a fresh cryptographically random state and a 43–128 character PKCE verifier for each attempt; keep the attempt tied to the user and expire it promptly.

Open the authorization endpoint with these parameters:

https://comick.dev/api/auth/oauth2/authorize
  ?response_type=code
  &client_id=YOUR_PUBLIC_CLIENT_ID
  &redirect_uri=dev.example.reader%3A%2Foauth%2Fcomick
  &scope=library%3Aread%20offline_access
  &resource=https%3A%2F%2Fapi.comick.dev%2Fintegrations%2Fv1
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

The line breaks above are for readability. Construct the URL with a URL-encoding library. Never collect the user's Comick password or load the authorization page in an embedded WebView.

Handle the callback and exchange the code

Accept callbacks only for the registered scheme/host/path and pending attempt. Validate state, reject duplicate or expired callbacks, and handle consent denial before exchanging a code. Consume the attempt once.

The following curl illustrates the request your native OAuth library must make:

curl --request POST 'https://comick.dev/api/auth/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_PUBLIC_CLIENT_ID' \
  --data-urlencode 'code=CODE_FROM_VALIDATED_CALLBACK' \
  --data-urlencode 'redirect_uri=dev.example.reader:/oauth/comick' \
  --data-urlencode 'code_verifier=ORIGINAL_VERIFIER' \
  --data-urlencode 'resource=https://api.comick.dev/integrations/v1'

Store and use tokens

Store refresh tokens in the platform's secure credential storage (Keychain on Apple platforms or storage protected by Android Keystore). Keep access tokens in memory where possible. Never include tokens in crash reports or analytics.

Send the access token in the Authorization: Bearer header to read the library. Serialize refresh attempts for each connection and atomically replace the refresh token after every successful refresh.

Users may decline offline access, sign out of their authorizing session, or disconnect the app. Treat those cases as a need to reconnect, following refresh and disconnect.