OAuth & sign-in

How dashboard sign-in works, and the GitHub OIDC shim Cognito calls during federated login.

dev · https://api.dev.oprag.ai

None of the 4 endpoints on this page need a dashboard session. They are part of the Integration API, which lists them alongside everything else your key opens.

Dashboard sign-in uses Amazon Cognito Hosted UI for email/password (invitation-only) and federated providers (Google, GitHub). The SPA loads Cognito settings from GET /config, then redirects users to Cognito — not to API routes named authorize or callback.

Federated sign-in

URLWhat it is
https://{cognitoDomain}.auth.{cognitoRegion}.amazoncognito.com/oauth2/authorizeCognito's authorize endpoint, built by the dashboard with PKCE. Not an oprag route.
https://app.{env}.oprag.ai/auth/callbackThe dashboard route that exchanges the code for tokens. Returned as oauthRedirectUri from GET /config.
https://ashutech-{env}-oprag.auth.us-east-1.amazoncognito.com/oauth2/idpresponseRegister this URL in Google and GitHub, not the dashboard callback.

The GitHub OIDC shim

GitHub sign-in uses Cognito's custom OIDC identity provider backed by a shim at {api_base_url}/v1/auth/github/*. Cognito calls the discovery document, token endpoint, and userinfo endpoint during federated login. The shim exchanges a GitHub OAuth authorization code (from Cognito) for a signed id_token Cognito can verify.

GET /v1/auth/github/.well-known/openid-configuration

OIDC discovery document for the GitHub sign-in shim.

Auth Public — no credential

Before you call it

  • Cognito fetches this when GitHub is configured as a custom OIDC provider.

Path parameters

None.

Query parameters

None.Serves a fixed document and takes no input at all.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "issuer": "https://api.dev.oprag.ai/v1/auth/github",
  "token_endpoint": "https://api.dev.oprag.ai/v1/auth/github/token",
  "userinfo_endpoint": "https://api.dev.oprag.ai/v1/auth/github/userinfo",
  "jwks_uri": "https://api.dev.oprag.ai/v1/auth/github/jwks",
  "response_types_supported": ["code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["RS256"]
}

Status codes

Status Meaning
200 Success.
429 Rate limited. See rate limits.
503 GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are not set.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/auth/github/.well-known/openid-configuration' \
  -H 'X-Oprag-Key: sk_live_...'
GET /v1/auth/github/jwks

JSON Web Key Set for verifying the shim's RS256 id_token signatures.

Auth Public — no credential

Path parameters

None.

Query parameters

None.Serves a fixed document and takes no input at all.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "github-oidc-1",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

Status codes

Status Meaning
200 Success.
429 Rate limited. See rate limits.
503 The GitHub OIDC shim is not configured.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/auth/github/jwks' \
  -H 'X-Oprag-Key: sk_live_...'
POST /v1/auth/github/token

Exchanges a GitHub OAuth authorization code for a signed id_token Cognito can verify.

Auth Public — no credential

Before you call it

  • Cognito calls this during GitHub federated login; your code never does.
  • Accepts application/x-www-form-urlencoded or JSON, and falls back to the query string for the three OAuth fields.
  • The response is OIDC-shaped but carries an id_token only — there is no access_token.
  • The GitHub account must have a verified email, or the exchange fails.

Path parameters

None.

Query parameters

Name Type Required Default Description
grant_type "authorization_code" Optional — Read only when the form-encoded body omits it. Anything else is rejected with 400.
code string Optional — GitHub authorization code. Read only when the form-encoded body omits it.
redirect_uri string Optional — Must match the code's redirect URI. Read only when the body omits it.

Body parameters

Defined by the caller.OAuth 2.0 token request, form-encoded, sent by Cognito during federated sign-in.

Request

JSON 
grant_type=authorization_code&code=abc123&redirect_uri=https%3A%2F%2Fashutech-dev-oprag.auth.us-east-1.amazoncognito.com%2Foauth2%2Fidpresponse&client_id=gh_client_example

Response

200 Success

JSON 
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIs..."
}

Status codes

Status Meaning
200 Success.
400 The request body failed validation.
429 Rate limited. See rate limits.

curl

Shell 
curl -X POST 'https://api.dev.oprag.ai/v1/auth/github/token' \
  -H 'X-Oprag-Key: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d 'grant_type=authorization_code&code=abc123&redirect_uri=https%3A%2F%2Fashutech-dev-oprag.auth.us-east-1.amazoncognito.com%2Foauth2%2Fidpresponse&client_id=gh_client_example'
GET /v1/auth/github/userinfo

User claims read from a valid GitHub shim id_token.

Auth Integration key

Before you call it

  • Cognito calls this after the token exchange, sending the id_token in an Authorization: Bearer header.

Path parameters

None.

Query parameters

None.Scoped by the calling credential, so there is nothing in the URL to narrow.

Body parameters

None.GET requests carry no body.

Response

200 Success

JSON 
{
  "sub": "12345",
  "email": "dev@example.com",
  "name": "Dev User",
  "preferred_username": "dev-user"
}

Status codes

Status Meaning
200 Success.
401 Missing, invalid, expired, or wrong-audience id_token.
403 Origin or IP not allowed for this project.
429 Rate limited. See rate limits.

curl

Shell 
curl -X GET 'https://api.dev.oprag.ai/v1/auth/github/userinfo' \
  -H 'X-Oprag-Key: sk_live_...'

Ready to ship?

Get started free