Proxy Endpoints

The proxy endpoints handle the OAuth flow between your application and OAuth providers. You redirect users to the proxy, and AuthGate handles the rest.

Initiate authentication

Call this endpoint from your server to initiate the OAuth flow. AuthGate validates the request, generates PKCE parameters, and returns a redirect URL to send the user to.

Headers

The Authorization: Bearer <api_key> header is required. The project is resolved automatically from the API key.

Request body

Response 200

{
  "redirect_url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}

Redirect the user to the returned redirect_url to start the OAuth flow with the provider.

Example

curl -X POST https://auth.example.com/api/proxy/github \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://myapp.com/auth/callback",
    "state": "redirect:/settings"
  }'

Validation

The endpoint validates the following before returning the redirect URL:

1. The Authorization header contains a valid API key
2. The provider is one of: google, github, discord, azure, apple
3. The API key resolves to an active project
4. The callback_url is registered for the project and provider
5. The provider is enabled for the project

If validation fails, a JSON error response is returned with the appropriate status code.

Callback handling

After the user authenticates with the provider, the provider redirects back to this endpoint. AuthGate then:

1. Validates the state and authorization code
2. Exchanges the code for access/ID tokens
3. Extracts user info from the provider
4. Creates or updates the end user record
5. Signs a JWT with the user's information
6. Redirects to your registered callback URL

Redirect to your callback

{callback_url}?token={jwt_token}&refresh_token={refresh_token}&state={state}

The token is a JWT signed with your project's signing secret. It expires in 5 minutes — verify it immediately using the Token Verification endpoint. The redirect includes Referrer-Policy: no-referrer to prevent token leakage via HTTP referrer headers.

JWT claims

{
  "sub": "user_abc123",
  "email": "user@example.com",
  "name": "Jane Doe",
  "picture": "https://avatars.githubusercontent.com/u/12345",
  "provider": "github",
  "project_id": "proj_xyz",
  "aud": "session",
  "iss": "authgate",
  "exp": 1234567890,
  "iat": 1234567590
}

Apple callback

Apple Sign In uses form_post response mode, so the callback is a POST request instead of GET. AuthGate handles this automatically — no special configuration is needed on your end.

Email authentication

For email + password authentication, AuthGate provides a separate set of endpoints that don't use the OAuth redirect flow. Instead, they accept JSON requests and return JWT tokens directly.

See the Email Auth Endpoints reference for the full API documentation.

Magic link authentication

Magic link authentication is a passwordless method controlled by its own provider toggle (independent from Email + Password). Users receive an email with a one-time link that signs them in automatically.

See the Email Auth Endpoints reference for the full API documentation.

SMS authentication

For SMS OTP authentication, AuthGate provides endpoints to send and verify one-time codes via SMS. Like email auth, these endpoints accept JSON requests and return JWT tokens directly.

See the SMS Auth Endpoints reference for the full API documentation.

Session management

After successful authentication, AuthGate returns a refresh_token alongside the JWT. Use this to maintain long-lived sessions without re-authenticating.

See the Session Management guide for full details.

Multi-factor authentication (MFA)

AuthGate supports TOTP, SMS, and backup code MFA. When MFA is enabled for a user, authentication returns a challenge token instead of a JWT. The challenge must be verified before a JWT is issued.

See the MFA guide and MFA Endpoints reference for full documentation.