Integrate your app with Accrawl

Start the OAuth request

Generate state and PKCE values for every attempt. The example uses Node.js built-in modules. Adapt session, request, and response to your web framework.

import { createHash, randomBytes } from 'node:crypto';

const baseUrl = 'https://accrawl.com';
const clientId = process.env.ACCRAWL_CLIENT_ID;
const redirectUri = 'https://your-app.example/callback';
if (!clientId) throw new Error('ACCRAWL_CLIENT_ID is not configured');

const verifier = randomBytes(32).toString('base64url');
const challenge = createHash('sha256')
  .update(verifier)
  .digest('base64url');
const state = randomBytes(16).toString('base64url');

session.accrawlOAuth = { state, verifier };

const authorizeUrl = new URL('/oauth/authorize', baseUrl);
authorizeUrl.search = new URLSearchParams({
  response_type: 'code',
  client_id: clientId,
  redirect_uri: redirectUri,
  scope: 'read:data',
  state,
  code_challenge: challenge,
  code_challenge_method: 'S256',
}).toString();

response.redirect(authorizeUrl.toString());

Handle the callback

Exchange the code from a trusted backend, or directly from a public client that has no backend. Omit client_secret for a public client.

const callbackUrl = new URL(request.url);
const pending = session.accrawlOAuth;
const returnedState = callbackUrl.searchParams.get('state');
const code = callbackUrl.searchParams.get('code');
const oauthError = callbackUrl.searchParams.get('error');

if (oauthError) throw new Error('Accrawl authorisation was not completed');
if (!pending || !code || returnedState !== pending.state) {
  throw new Error('Invalid Accrawl OAuth callback');
}
delete session.accrawlOAuth;

const form = new URLSearchParams({
  grant_type: 'authorization_code',
  code,
  redirect_uri: redirectUri,
  client_id: clientId,
  code_verifier: pending.verifier,
});
if (process.env.ACCRAWL_CLIENT_SECRET) {
  form.set('client_secret', process.env.ACCRAWL_CLIENT_SECRET);
}

const tokenResponse = await fetch('https://accrawl.com/oauth/token', {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: form,
});
if (!tokenResponse.ok) {
  throw new Error(`Accrawl token exchange failed (${tokenResponse.status})`);
}
const tokens = await tokenResponse.json();

Refresh

Implement saveTokensAtomically as one database transaction that replaces both stored tokens.

function clientForm(fields) {
  const form = new URLSearchParams({ ...fields, client_id: clientId });
  if (process.env.ACCRAWL_CLIENT_SECRET) {
    form.set('client_secret', process.env.ACCRAWL_CLIENT_SECRET);
  }
  return form;
}

const refreshResponse = await fetch('https://accrawl.com/oauth/token', {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: clientForm({
    grant_type: 'refresh_token',
    refresh_token: storedRefreshToken,
  }),
});
if (!refreshResponse.ok) throw new Error('Accrawl token refresh failed');
const replacementTokens = await refreshResponse.json();

await saveTokensAtomically(replacementTokens);

Disconnect

const revokeResponse = await fetch('https://accrawl.com/oauth/revoke', {
  method: 'POST',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  body: clientForm({
    token: storedRefreshToken,
    token_type_hint: 'refresh_token',
  }),
});
if (!revokeResponse.ok) throw new Error('Accrawl token revocation failed');