Authorization code flow

Sign a user in with Gigadrive end to end, from the PKCE challenge to the ID token and the refresh that follows.

Access is granted per request

This flow needs an OAuth client that Gigadrive created for you. There is no dynamic registration endpoint. See Requesting access.

The authorization code flow is how a web or mobile application signs a person in with their Gigadrive account. Use the device flow instead when there is no browser to redirect, such as in a terminal.

The exchange

Generate a PKCE verifier and challenge
The verifier is 43 to 128 characters from A-Z a-z 0-9 - . _ ~. The challenge is its SHA-256 hash, base64url encoded without padding. Keep the verifier; you send it at step 4.
```
VERIFIER=$(openssl rand -base64 60 | tr -d '=+/' | cut -c1-64)
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -binary -sha256 \
  | openssl base64 | tr '+/' '-_' | tr -d '=')
printf 'verifier=%s\nchallenge=%s\n' "$VERIFIER" "$CHALLENGE"
```
PKCE is mandatory for public clients, and S256 is the only method accepted. A confidential client may omit it, and gains nothing by doing so.
Send the user to the authorize endpoint
Every parameter in the following authorization request is required, state included. Generate state per attempt and check it on the way back, or you have no protection against a forged callback.
```
https://idp.gigadrive.de/oauth2/authorize
  ?client_id=3f1c9a72-5d84-4a1e-9c31-8b6f0d4e7a52
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &response_type=code
  &scope=openid%20profile%20email%20offline_access
  &state=8xQ2mBv1
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
```
An unauthenticated visitor is redirected to Gigadrive sign-in and comes back here once they are done, so you do not handle that case yourself.
The user approves on the consent screen
The screen names your client and lists what it is asking for. It appears on every sign-in, because an earlier approval does not carry over. Declining redirects to your redirect_uri with error=access_denied.

Exchange the code

You receive code and state on your redirect URI. Verify state, then exchange the code within 10 minutes. It is single-use.

curl -X POST https://idp.gigadrive.de/oauth2/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "3f1c9a72-5d84-4a1e-9c31-8b6f0d4e7a52",
    "code": "b7d1f0a5c93e4d2fa6108c7b5e2d9f4a",
    "redirect_uri": "https://app.example.com/callback",
    "code_verifier": "'"$VERIFIER"'"
  }'

A confidential client sends its secret too, either as client_secret in the body or as HTTP Basic credentials.

Validate what comes back

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "expires_in": 300,
  "scope": "openid profile email offline_access",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "refresh_token": "9f3c...b21e"
}

Verify the id_token against the JWKS at https://idp.gigadrive.de/.well-known/jwks.json, selecting the key by the token's kid. Check iss is https://idp.gigadrive.de, aud is your client id, and nonce matches the one you sent if you sent one.

What each token is for

The access token lives 300 seconds and carries the granted scopes. Present it to /oauth2/userinfo or to api.gigadrive.network, both of which accept it on the Authorization header.

Treat the ID token as proof of who signed in, never as a credential for calling anything.

The refresh token exists only if offline_access was granted, and lives 30 days. Refreshing rotates it: the response contains a new refresh token and the one you sent stops working, so persist the new value before you do anything else.

curl -X POST https://idp.gigadrive.de/oauth2/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "refresh_token",
    "client_id": "3f1c9a72-5d84-4a1e-9c31-8b6f0d4e7a52",
    "refresh_token": "9f3c...b21e"
  }'

Failures worth handling

What you see	What happened
`400 invalid_client`, "Unsupported response_type"	Something other than `code`
`400 invalid_request` at authorize	The redirect URI is not registered, or does not match exactly
Redirect with `error=invalid_scope`	A scope is unknown, or the client may not request it
Redirect with `error=access_denied`	The user declined, the account is suspended, or a sign-in policy refused it
`400 invalid_request`, "invalid_grant"	The code was reused, expired, or belongs to another client or redirect URI
`400 invalid_request`, "pkce_required"	A public client sent no code challenge
`401 invalid_client` at token	Wrong or missing client credentials
`503 temporarily_unavailable`	Gigadrive could not verify the session right now. Retry

A code that verified fine can still be refused at redemption. Suspension, a sign-in policy change, and a withdrawn product entitlement are all re-checked at that moment, because up to ten minutes pass between approval and exchange.