OAuth & OpenID Connect (OIDC)

Standards-compliant OAuth 2.0 authorization server with OpenID Connect support

Overview

Instafill.ai's OAuth 2.0 implementation operates in two roles simultaneously. As a consumer, it lets users sign in with Google or Microsoft credentials — the same flows described in Authentication & Security. As an authorization server, it issues tokens to third-party applications that want to access the Instafill.ai API on behalf of a user, with OAuth client records managed per workspace.

The authorization server implements the Authorization Code flow with PKCE (Proof Key for Code Exchange, RFC 7636). Tokens issued by the authorization server are JWTs in the same format used for all other auth methods, so they are validated by shared authentication middleware without any special-case handling.

Key Capabilities

• Authorization Code Flow with PKCE: RFC 7636 compliant; the code verifier/challenge exchange prevents authorization code interception even over non-TLS channels
• OAuth Client Registry: Third-party applications register as clients; client records are stored and managed per workspace
• Consistent Token Format: Access tokens are JWTs validated by the same middleware used for password and OAuth provider logins across all service layers
• Consumer Role — Google & Microsoft: Provider-specific flows handle sign-in with external IdPs and normalize the result into a standard Instafill.ai JWT
• Scope-Based Permissions: Tokens carry only the scopes approved by the user during the consent step; downstream middleware enforces scope restrictions
• Token Lifecycle: Short-lived access tokens with refresh token support for long-lived integrations; token revocation terminates access immediately
• JWKS Endpoint: Public keys published for third-party verification of token signatures

How It Works

Instafill.ai as authorization server (for third-party app developers):

1. Register an OAuth client in Developer Settings — provide redirect URI and app name; receive a client_id and client_secret
2. Generate a PKCE code_verifier and code_challenge in your application (RFC 7636)
3. Redirect the user to the Instafill.ai authorization endpoint with code_challenge, requested scopes, and state parameter
4. User authenticates (via any supported method) and reviews the consent screen listing the requested scopes
5. A short-lived authorization code is issued to your redirect URI
6. Exchange the code plus code_verifier for an access token and optional refresh token — the PKCE pair is validated before issuing
7. Use the access token as a Bearer token on Instafill.ai API requests; the JWT middleware in both service layers validates it

Instafill.ai as OAuth consumer (for end users signing in):

1. User clicks "Sign in with Google" or "Sign in with Microsoft"
2. The appropriate provider logic initiates the OAuth handshake with the external IdP
3. The IdP returns an identity assertion (email, display name) — no password is transmitted to Instafill.ai
4. The identity is mapped to an Instafill.ai account and a JWT is issued
5. The resulting JWT is identical in structure to tokens issued for email/password logins

Use Cases

OAuth/OIDC is used wherever Instafill.ai authentication needs to be embedded in external systems without sharing passwords. Automation platforms such as Zapier and Make.com use the authorization code flow so users grant Instafill.ai access during integration setup — the platform receives a scoped token rather than stored credentials. Enterprise portals configure Instafill.ai as an OAuth client to a corporate identity provider so employees get seamless access after logging into their IdP once. Mobile and desktop applications use PKCE to safely complete the flow without a server-side component that could protect a client secret.

Benefits

• No Password Sharing: Third-party apps receive a scoped JWT — they never handle the user's Instafill.ai password
• PKCE Closes the Interception Gap: Even if an authorization code is leaked in a redirect, the attacker cannot exchange it without the original code_verifier
• Unified Token Validation: OAuth-issued JWTs pass through the same middleware as all other tokens; no separate validation path required
• Granular Scope Control: Users approve specific scopes (e.g., forms:read, sessions:write) at consent time; the token cannot exceed those permissions
• Revocable Access: Users or admins can revoke a client's token at any time; revocation takes effect immediately across both service layers
• Standard Interoperability: Authorization code flow with PKCE works with any OAuth 2.0 client library

Security & Privacy

All data is workspace-scoped and protected by JWT authentication middleware running across all service layers.

PKCE (RFC 7636): The code_challenge is sent at authorization time; the code_verifier is sent only at token exchange. An intercepted authorization code cannot be used without the verifier, which never leaves the legitimate client.

Short-Lived Access Tokens: Access tokens carry an expiration claim. Expired tokens are rejected by the middleware without any additional lookup.

Scope Enforcement: Token scopes are embedded as claims. Middleware checks scope claims against the operation being requested — a token with only forms:read cannot create or modify sessions.

Client Secret Protection: Client secrets are stored hashed. A leaked client_id without the secret cannot complete a confidential client token exchange.

Revocation: Revoking a client's access immediately blocks further token issuance and invalidates existing refresh tokens for that client.

Audit Logging: Authorization grants, token issuances, and revocations are logged with client ID, user, timestamp, and scopes.

Common Questions