Quick Start

Get started with oidc.pub in minutes. Register a service, update your issuer URL, upload your OIDC configuration, and your discovery endpoint is live.

Step 1: Create a service

Sign in and register a new OIDC service. Paid plans can choose a custom subdomain. Free tier services receive an auto-assigned subdomain.

npx oidc.pub login
npx oidc.pub service create \
  --name "My Service" \
  --subdomain myservice

docker run --rm -it \
  -v ~/.config/oidcpub:/home/oidcpub/.config/oidcpub \
  registry.gitlab.com/oidc.pub/cli:latest login

docker run --rm -it \
  -v ~/.config/oidcpub:/home/oidcpub/.config/oidcpub \
  registry.gitlab.com/oidc.pub/cli:latest \
  service create \
  --name "My Service" \
  --subdomain myservice

curl -X POST https://oidc.pub/api/services \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Service",
    "subdomain": "myservice"
  }'

Step 2: Update your issuer URL

Configure your service to use https://myservice.oidc.pub as its issuer. Tokens minted after this change will carry the correct issuer claim that matches the public discovery endpoint.

Step 3: Upload your OIDC configuration

Push your openid-configuration and JWKS. Use the CLI sync command to fetch configuration directly from your issuer, or upload it manually via the API. The API rewrites the issuer and jwks_uri fields to point to your oidc.pub subdomain automatically.

npx oidc.pub service sync \
  --service myservice \
  --source-url https://your-issuer.internal \
  --once

docker run --rm -it \
  -v ~/.config/oidcpub:/home/oidcpub/.config/oidcpub \
  registry.gitlab.com/oidc.pub/cli:latest-sync \
  --service myservice \
  --source-url https://your-issuer.internal \
  --once

SERVICE_SUBDOMAIN=myservice

curl -X PUT https://oidc.pub/api/services/$SERVICE_SUBDOMAIN/config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "openidConfiguration": {
      "issuer": "https://myservice.oidc.pub",
      "jwks_uri": "https://myservice.oidc.pub/.well-known/jwks.json",
      "response_types_supported": ["id_token"],
      "subject_types_supported": ["public"],
      "id_token_signing_alg_values_supported": ["RS256"]
    },
    "jwks": {
      "keys": [
        {
          "kty": "RSA",
          "kid": "key-1",
          "use": "sig",
          "alg": "RS256",
          "n": "...",
          "e": "AQAB"
        }
      ]
    }
  }'

Use the service subdomain as the API route reference. Existing UUID service IDs are still accepted for compatibility.

Step 4: Verify

Your OIDC discovery endpoint is live within 60 seconds.

curl https://myservice.oidc.pub/.well-known/openid-configuration | jq .