List configured providers

GET /api/auth/oauth open

Every provider with a client configured, keyed by name. Providers with nothing configured are left out entirely — so a sign-in page can render exactly the buttons that will work, rather than a row of options that fail on click.

google is the provider implemented today.

Parameters

provider string

Narrow to one provider. Query parameter.

Returns

{ configs } keyed by provider, or { provider, config } when one was named.

Request

curl https://example.com/api/auth/oauth

Response

{
  "configs": {
    "google": { "clientId": "1234.apps.googleusercontent.com", "redirectURI": "https://example.com/api/auth/oauth/google/exchange" }
  }
}

Begin a provider's flow

GET /api/auth/oauth/:provider open

Redirects the browser to the provider's consent screen. Navigate to it — do not fetch it — since the whole point is to hand the person to the provider and get them back at /api/auth/oauth/:provider/exchange.

A provider with no implementation answers 404 naming it.

Parameters

provider enum Required

Path parameter.

Possible enum values

google

Returns

A redirect to the provider.

Request

curl -i https://example.com/api/auth/oauth/google

Response

{
  "provider": "unsupported"
}

Exchange the provider code for a session

GET /api/auth/oauth/:provider/exchange open

The redirect target the provider sends the browser back to. Exchanges the authorization code for the provider's tokens, resolves or creates the identity behind the account, and sets the session cookies.

This is a URL the provider calls, not one a client calls directly — it is documented so the redirect can be configured to match.

Parameters

provider enum Required

Path parameter.

Possible enum values

google

code string Required

The authorization code, from the provider. Query parameter.

state string

The state the flow was started with. Query parameter.

Returns

A redirect back into the site, with both session cookies set.

Request

curl -i "https://example.com/api/auth/oauth/google/exchange?code=4/0Ad…&state=…"

Response

{
  "identity": { "id": "01J2788XY98FDTA410C8S716CD", "kind": "member" }
}

Read a provider's configuration

GET /api/auth/oauth/:provider/config admin

The stored client configuration for one provider. An unimplemented provider answers 404 naming it.

Parameters

provider enum Required

Path parameter.

Possible enum values

google

Returns

{ config }.

Request

curl https://example.com/api/auth/oauth/google/config \
  -H "authorization: Bearer $TOKEN"

Response

{
  "config": {
    "clientId": "1234.apps.googleusercontent.com",
    "redirectURI": "https://example.com/api/auth/oauth/google/exchange"
  }
}

Set a provider's configuration

POST /api/auth/oauth/:provider/config admin

Writes the client credentials the flow runs with. A body that is not JSON answers 400.

Parameters

provider enum Required

Path parameter.

Possible enum values

google

clientId string Required

The provider's client id.

clientSecret string Required

The provider's client secret.

redirectURI string

Where the provider sends the browser back. Defaults to this deployment’s exchange route.

Returns

{ config } as written.

Request

curl -X POST https://example.com/api/auth/oauth/google/config \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  -d '{ "clientId": "1234.apps.googleusercontent.com", "clientSecret": "…" }'

Response

{
  "config": {
    "clientId": "1234.apps.googleusercontent.com",
    "redirectURI": "https://example.com/api/auth/oauth/google/exchange"
  }
}

Remove a provider's configuration

DELETE /api/auth/oauth/:provider/config admin

Forgets the credentials. The provider then disappears from GET /api/auth/oauth, which is how a sign-in page stops offering it.

Parameters

provider enum Required

Path parameter.

Possible enum values

google

Returns

200.

Request

curl -X DELETE https://example.com/api/auth/oauth/google/config \
  -H "authorization: Bearer $TOKEN"

Response

{
  "ok": true
}

Check whether a provider is usable

GET /api/auth/oauth/:provider/config/validity admin

Whether the stored configuration would actually work — the difference between "credentials are set" and "credentials are right", which otherwise only shows up when somebody tries to sign in.

Parameters

provider enum Required

Path parameter.

Possible enum values

google

Returns

200 when valid; 409 with { issues } when not.

Request

curl https://example.com/api/auth/oauth/google/config/validity \
  -H "authorization: Bearer $TOKEN"

Response

{
  "issues": ["redirectURI does not match the configured origin"]
}

Check validity without the reasons

HEAD /api/auth/oauth/:provider/config/validity admin

The same check with no body — 200 or 409.

Parameters

provider enum Required

Path parameter.

Possible enum values

google

Returns

200 when valid, 409 when not.

Request

curl -I https://example.com/api/auth/oauth/google/config/validity \
  -H "authorization: Bearer $TOKEN"

Response

{}

Render only what will work

The flow

Configuration

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns

Parameters

Returns