OAuth reference
Authorization parameters, permissions, token exchange, and callback rules.
Discovery
curl 'https://comick.dev/api/auth/.well-known/oauth-authorization-server'Use the published endpoint URLs. Comick supports the authorization-code grant with S256 PKCE and optional refresh tokens. Dynamic client registration, machine-to-machine grants, and OpenID Connect identity scopes are unavailable.
Authorization request
Navigate the user's browser to https://comick.dev/api/auth/oauth2/authorize using a query constructed by your URL library.
| Parameter | Value |
|---|---|
response_type | code |
client_id | Your registered client ID |
redirect_uri | An exact registered callback URL |
scope | library:read, optionally followed by offline_access |
resource | https://api.comick.dev/integrations/v1 |
state | Fresh random value bound to the initiating application session |
code_challenge | Base64url-encoded SHA-256 hash of the verifier, without padding |
code_challenge_method | S256 |
The verifier must be a cryptographically random, 43–128 character string using unreserved URI characters. A random 32-byte value encoded as base64url is suitable. PKCE is required for confidential clients as well as public clients. Plain PKCE is not supported.
Comick presents the registered app name, description, and requested permissions. Users can decline the request or optional offline access. Development apps are labeled and restricted to their owner.
Callback
Successful authorization redirects to your callback with code and state. A denial can return error=access_denied and state. Verify the state against the unexpired, one-time attempt before handling either outcome.
Codes are short-lived and single-use. Exchange immediately; never retry a consumed code. If you lose the exchange response, restart authorization rather than assuming another exchange is safe. An invalid callback may be rejected on Comick without redirecting to your site.
Token request
Send POST https://comick.dev/api/auth/oauth2/token with Content-Type: application/x-www-form-urlencoded.
| Field | Value |
|---|---|
grant_type | authorization_code |
code | Code from the validated callback |
redirect_uri | Same callback used in authorization |
code_verifier | Original verifier for this attempt |
resource | https://api.comick.dev/integrations/v1 |
client_id | Required in the form for public clients |
Confidential clients authenticate with HTTP Basic (client_secret_basic). Public clients use no secret or Basic header. Cross-origin browser requests use credentials: "omit".
An example token response is:
{
"access_token": "OPAQUE_ACCESS_TOKEN",
"token_type": "Bearer",
"expires_in": 900,
"scope": "library:read offline_access",
"refresh_token": "OPAQUE_REFRESH_TOKEN"
}The refresh token is optional. Inspect granted scope rather than assuming the user approved everything. Access tokens last 15 minutes; refresh tokens last 30 days and rotate when used. Token validity can end sooner because of revocation, session expiry, account eligibility, or suspension.
Tokens are opaque credentials: do not decode them as JWTs, extract a user ID, or use them for Comick account-management endpoints. See refresh and disconnect and errors.