Applications

The authorization-code + PKCE flow

1 · Send the person to the authorization endpoint

A top-level navigation, not a fetch. Generate a random code_verifier, keep it server-side or in session storage, and send its SHA-256 digest, base64url-encoded, as the challenge.

https://auth.civicgate.org/api/v1/oauth/authorize
  ?response_type=code
  &client_id=my-community-site-9f2a1c4b7e08
  &redirect_uri=https://example.com/auth/callback
  &scope=openid%20profile%20email
  &state=<random; compare it on the way back>
  &nonce=<random; compare it to the id_token's nonce claim>
  &code_challenge=<BASE64URL(SHA256(code_verifier))>
  &code_challenge_method=S256

openid is required — without it the request fails with invalid_scope. PKCE is required for every self-registered application, public or confidential: registration forces require_pkce on and it is not editable.

2 · They sign in and approve

Not signed in, they are sent to https://www.civicgate.org/login with the full authorize URL as next, and return here afterwards. Then CivicGate shows a consent screen naming your application and listing, in plain language, what it is asking for. Approval is carried by a server-minted nonce valid for 10 minutes, so an authorize URL with consent=granted pasted on cannot approve anything — never bookmark or replay a consent URL; build a fresh authorize request each time.

3 · CivicGate redirects back with a code

302 → https://example.com/auth/callback?code=…&state=…

Compare state to what you sent. The code lives 2 minutes and is single-use. If something went wrong after the redirect URI was validated, you get ?error= + error_description= instead — invalid_scope, unsupported_response_type, unauthorized_client, invalid_request. If it went wrong before that (unknown client, or a redirect URI that is not registered) the error renders on CivicGate and no redirect happens at all, because redirecting to an unvalidated address is the exact attack this endpoint exists to refuse.

4 · Exchange the code for tokens

curl -X POST https://auth.civicgate.org/api/v1/oauth/token \
  -u 'my-community-site-9f2a1c4b7e08:cgs_…' \
  -d grant_type=authorization_code \
  -d code=… \
  -d redirect_uri=https://example.com/auth/callback \
  -d code_verifier=…

{
  "access_token": "…",
  "id_token": "…",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "openid profile email"
}

Read the scope you got back — the granted set can be narrower than the set you asked for, and code that assumes otherwise misbehaves the first time a scope is refused. A public client sends no secret; its code_verifier is what proves it is the same party that started the flow.

redirect_uri must match the one the code was issued against. Failures are deliberately indistinguishable — unknown, expired and already-redeemed codes all answer invalid_grant, because saying which would help only somebody who had stolen one. One exception worth knowing: access_denied means the code was fine and the person is not authorised for that application, which sends you to an administrator rather than to your PKCE implementation.

5 · Verify the id_token

RS256, verified against JWKS — pick the key by the token's kid header, which is what makes a key rotation a non-event. Check iss, aud (your client id), expiry, and that nonce equals what you sent. Claims are filtered by scope: with only openid you get a subject and nothing else — not the name, not the email.

6 · Use the access token

curl https://auth.civicgate.org/api/v1/oauth/userinfo -H 'Authorization: Bearer …'

The same token authenticates that user against the CivicGate GraphQL API, which is what makes an Application able to write on their behalf. Two things to know before you build on that:

• Mutations go to https://www.civicgate.org/graphql. The public endpoint api.civicgate.org/graphql is read-only for every credential and refuses mutations regardless of who you are.
• What you can call with it is the generated schema reference: /api/reference.
• A client_credentials token is not a CivicGate API credential. The gateway recognises service tokens and rejects them, deliberately — there is no app-scoped authorisation model yet, so "not this credential" is said out loud rather than returned as an empty result set that looks like an empty account. Self-registered applications cannot hold that grant in any case.

Redirect URI rules

This is the control the whole flow rests on. The authorize endpoint delivers a user's authorization code to whatever address your client names, and the only thing stopping an attacker naming their own is that it must already appear — character for character — in your registered list. Everything below exists so that exact match cannot be written loosely enough to stop meaning anything.

The loopback exception is checked on the parsed host, not on a string prefix: http://localhost.attacker.net/cb begins with http://localhost and is a completely different, attacker-controlled host. Only localhost, 127.0.0.1 and ::1 qualify, on any port.

Stored values are trimmed of spaces and de-duplicated, and otherwise kept byte for byte. Nothing is lowercased and no trailing slash is added or removed, because the stored string is what the authorize endpoint compares against — "helpfully" normalising it would store something your client never sends, and every login would fail with a mismatch you did not cause. Register https://example.com/cb and https://example.com/cb/ separately if you use both.

The rules are enforced identically on edit as on registration. A rule that only applies at creation is not a rule.

Scopes

Space-separated in scope. Unknown values are ignored, not rejected.

A self-registered application may request openid, profile and email, and asking for anything else is refused rather than silently trimmed — a silent drop would leave you with a client that authorises fine and then returns a token missing the claim you built on, with nothing anywhere explaining why. The message names the alternative:

A self-registered application may request only these scopes: openid, profile, email.
"civic:positions" is granted by a CivicGate administrator — contact us if your
application needs it.

The civic:* scopes read data a member has not agreed to hand to a stranger, so they are a human decision rather than a form field. The two marked sensitive carry political-belief data about a private individual and re-prompt on every authorization, even for a client the person approved before — silence must never be read as consent for that.

Token lifetimes and refresh

You probably will not get a refresh token

A refresh token is returned only when both hold: the granted scopes include offline_access, and the client is registered for the refresh_token grant. Self-registered clients are registered for the grant — and cannot request offline_access, so in practice they never receive one. That is deliberate: standing long-lived access to somebody's account is not something a registration form should be able to award itself.

So the normal pattern for a self-service application is: hold your own session for the person, and when you need CivicGate again, run the authorization flow again. Because they already consented, and their identity-server session is still live, the round trip is silent — no second consent screen unless a sensitive scope is involved.

If an administrator has granted your application offline_access:

curl -X POST https://auth.civicgate.org/api/v1/oauth/token \
  -u 'CLIENT_ID:CLIENT_SECRET' \
  -d grant_type=refresh_token \
  -d refresh_token=…

A refresh token is bound to the client it was issued to and cannot be redeemed by another, so a token you obtained by any other route will be refused here.

Signing out

https://auth.civicgate.org/api/v1/oauth/logout?client_id=…&post_logout_redirect_uri=https://example.com/

The redirect target must be registered as a post-logout URI on your client — same reason as the authorize endpoint, otherwise this is an open redirect wearing a logout costume. Unregistered (or omitted), it answers a plain JSON acknowledgement instead of redirecting.

Rate limits — whose budget you are spending

An Application spends the budget of the user who authorised it, not its own. This is not obvious and it changes how you plan capacity.

• Ten users means ten separate budgets. Your application has no aggregate cap of its own.
• One user hammering through your app exhausts only their own budget. Their neighbours are unaffected.
• Every user's limit is set by their account tier, not yours. A free-tier user is metered at the free rate even if you are not.
• Reads and writes share one budget. There is no separate write allowance.

Practically: batch per-user work, cache what you can, and do not fan a single background job across many users' tokens expecting a pooled ceiling — you will hit each of them in turn.

The tier numbers, the RATE_LIMITED error shape and the retryable flag are all on the API guide, which is the one place they are stated: /help/api → Rate limits.

Troubleshooting

Known gaps

Stated rather than left to be discovered, because both change what you can promise your users.

• Token revocation is advertised and not implemented. The discovery document names https://auth.civicgate.org/api/v1/oauth/revoke; that URL answers 404. Do not build a sign-out that depends on it. Tokens expire on the schedule above, and an application can be stopped outright by disabling or deleting it, or by rotating its secret.
• There is no self-service consent withdrawal yet. The consent screen says a person can revoke access in their account settings; that surface does not exist at the moment. Until it does, deleting your application is what clears its consents — so if a user asks you to disconnect them, do it on your side and say so honestly.

Related

• Settings → Applications — register and manage yours.
• API guide — credentials, rate limits, error handling.
• API keys — the read-only credential, for when nobody signs in.
• Schema reference — every query, mutation and type you can call as the signed-in user.
• Public API — the endpoint and what the data covers.
• Discovery document — point your OIDC library at it.