Sign in with Google

Connect a browser sign-in flow to the CaseKit API, then select or join a workspace.

Before you begin

Google sign-in uses CaseKit’s configured Amazon Cognito authorization service. Ask your CaseKit operator for the approved auth domain, app client ID, API base URL, and registered callback URL for your integration. These must belong to the same environment. A custom callback must be approved and configured before it can receive a code; there is no public client-registration endpoint.

The existing dashboard handles this flow for dashboard users. Its cookie-based login and callback routes are not an integration API. Your integration owns its callback and server session. Call the CaseKit JSON API from a trusted server; it currently does not offer browser CORS.

1. Redirect to Google

Generate a fresh, cryptographically random OAuth state and PKCE verifier for each attempt. Keep them in a short-lived server session tied to the browser. Compute the challenge as the unpadded base64url encoding of SHA-256 over the verifier.

Redirect the browser to {authDomain}/oauth2/authorize with these URL-encoded parameters: 

response_type=code
client_id={approvedClientId}
redirect_uri={registeredCallbackUrl}
scope=openid email aws.cognito.signin.user.admin
identity_provider=Google
state={randomState}
code_challenge_method=S256
code_challenge={pkceChallenge}

Google returns through Cognito, which redirects to your registered callback. The Google-to-Cognito callback is configured by the operator; it is different from your application callback.

2. Exchange the authorization code

At your callback, reject errors, missing or mismatched state, and expired or already-consumed login attempts. Exchange the code from your server at {authDomain}/oauth2/token, using Content-Type: application/x-www-form-urlencoded: 

grant_type=authorization_code
client_id={approvedClientId}
code={returnedAuthorizationCode}
redirect_uri={sameRegisteredCallbackUrl}
code_verifier={originalPkceVerifier}

Use the client authentication configured by your operator, if required. Keep any client secret on the server. Consume the login attempt after successful exchange and establish your own secure session.

Cognito returns OAuth fields such as access_token, refresh_token, and expires_in. Use the Cognito access token for CaseKit requests. Google tokens and Cognito ID tokens are not accepted by the API. Provider token responses use snake_case; CaseKit’s JSON authentication routes use camelCase.

3. Verify your email before joining a workspace

A Google email-verification claim alone does not satisfy CaseKit’s current-mailbox check for creating or joining a workspace. With the Cognito access token, call:

  1. POST /v1/email-verification/request, with no body.
  2. POST /v1/email-verification/confirm, with JSON {"code":"the-received-code"}.

Both calls return 204 on success and use Authorization: Bearer {accessToken}. The proof is bound to your current identity and email and lasts 15 minutes. Requesting a new code replaces the previous challenge.

Then list invitations with GET /v1/invitations and accept one with POST /v1/invitations/{invitationId}/accept, or create a workspace with POST /v1/tenants. Those mutations require a UUID Idempotency-Key; see their request schemas in the reference. Matching email addresses do not automatically link Google and password accounts.

4. Select a workspace and call the API

Use GET /v1/memberships to discover existing memberships. For workspace requests, send: 

Authorization: Bearer {cognitoAccessToken}
X-Helpdesk-Tenant-Id: {tenantIdFromMembership}

A workspace is named tenant in the API contract. The selector grants no permission by itself; the API checks current membership and workspace policy. Existing membership access does not require repeating the 15-minute joining proof, but still requires current verified mailbox state.

Session lifetime and sign-out

Keep tokens out of URLs and logs. Use the configured provider refresh and revocation flow for your OAuth client. When using CaseKit’s JSON refresh/sign-out endpoints, follow their documented request and response schemas; refresh uses {"refreshToken":"…"}, and an omitted replacement refresh token means retain the previous one. Sign-out revokes the submitted refresh-token family, not every device. Clear your own session as well.

Google manages Google MFA. CaseKit’s native authenticator endpoints do not add a second factor to Google’s login.

Provider details: Cognito PKCE and token exchange.