Sign in with Escanor (OIDC)

Escanor runs an OpenID Connect provider for applications and MCP clients. Use discovery to learn the endpoints and supported capabilities of the deployment you are connecting to. An ID token identifies a user to your application; an access token authorizes a resource request. They are not interchangeable.

Prerequisites and discovery#

You need an Escanor account, a callback URL you control, and an OAuth/OIDC client library that supports authorization code with S256 PKCE. Use HTTPS callbacks in production. Native applications can use loopback callbacks, which have special port-matching rules.

curl -fsS https://api.escanor.in/.well-known/openid-configuration

The response includes issuer, authorization_endpoint, token_endpoint, jwks_uri, scopes_supported and code_challenge_methods_supported. Match the issuer exactly when validating tokens. Escanor also serves authorization server metadata at /.well-known/oauth-authorization-server. Discover URLs rather than hard-coding the following paths.

Endpoint reference#

Register a public client#

Open registration is configurable. When available, it creates a public client without a secret. Public clients cannot use the client-credentials flow; that requires a confidential client provisioned separately.

curl -fsS https://api.escanor.in/oidc/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "Example application",
    "redirect_uris": ["https://app.example/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "none",
    "scope": "openid profile email offline_access mcp:read"
  }'

Success returns HTTP 201 with client_id, metadata, registration_client_uri and registration_access_token. Store the registration token securely; Escanor returns it at creation, and it differs from an end-user token. Do not put it into a browser bundle or repository. Use the returned registration URI with that bearer token to read, replace permitted metadata or delete the registration.

Scopes and consent#

Request only what your application needs. The user can decline optional scopes. Read the granted scope set; do not assume it equals the requested set or that missing profile fields are errors.

Authorization code with PKCE#

Use your OAuth library to generate a random verifier and its BASE64URL(SHA256(verifier)) challenge. Keep the verifier, random state and OIDC nonce bound to this browser transaction. Never use the literal placeholders below.

GET https://api.escanor.in/oidc/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fapp.example%2Fcallback
  &scope=openid%20profile%20email%20offline_access%20mcp%3Aread
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=S256_CHALLENGE
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fmcp.escanor.in

The user signs in and consents. On callback, verify state and handle any returned OAuth error. Exchange the code only once, with the original verifier and identical callback URL:

curl -fsS https://api.escanor.in/oidc/token \
  --data-urlencode grant_type=authorization_code \
  --data-urlencode client_id=YOUR_CLIENT_ID \
  --data-urlencode code=RETURNED_CODE \
  --data-urlencode redirect_uri=https://app.example/callback \
  --data-urlencode code_verifier=ORIGINAL_VERIFIER

The response contains access_token, token_type, expires_in and granted scope. id_token and refresh_token depend on scopes. Use returned lifetimes. Validate the ID token with discovered JWKS: signature, issuer, audience, expiry and nonce. Refresh keys when an unfamiliar key identifier appears. Use a maintained OIDC library; decoding a JWT does not verify it.

MCP resource access#

The resource parameter names the token audience. For Escanor MCP use https://mcp.escanor.in, subject to advertised configuration. Listing needs mcp:read; invoking needs mcp:invoke. Provider credentials, permissions and confirmation checks still apply.

https://mcp.escanor.in/.well-known/oauth-protected-resource identifies the authorization server. An unauthenticated MCP request receives a 401 challenge pointing to this metadata. Compatible clients can discover and register automatically. See MCP for tool schemas and examples.

Refresh and revocation#

curl -fsS https://api.escanor.in/oidc/token \
  --data-urlencode grant_type=refresh_token \
  --data-urlencode client_id=YOUR_CLIENT_ID \
  --data-urlencode refresh_token=CURRENT_REFRESH_TOKEN

Refresh tokens rotate. Store the replacement atomically and serialize refreshes per session: replaying a retired token revokes its lineage. invalid_grant requires new sign-in/consent. Retry transient network/server errors with backoff; they are not evidence of revocation.

For revocation, send the token to the discovered endpoint using your client's authentication method. Register the exact post_logout_redirect_uri before provider logout. Ending a provider session can revoke provider tokens; local app logout and provider logout have different effects.

Failure recovery and limitations#

• Invalid redirect/client metadata: compare the registered URI, including scheme and path. Loopback port flexibility does not permit arbitrary redirects.
• invalid_grant: a code expired, was reused, or verifier/redirect differs; a refresh token may be retired. Restart authorization instead of redeeming repeatedly.
• Invalid scope/resource: use advertised scopes and configured audiences. Do not substitute a broader credential for denied access.
• access_denied: respect consent and let the user retry deliberately.
• login_required with prompt=none: open interactive sign-in.
• Registration disabled: ask Support about client setup.

Only code response type and S256 challenges are supported. Discovery is the deployment contract; not every advertised grant is available to every client. Related: API and keys, Accounts and sessions.