Provision Supabase users with SCIM

Create, update and block Supabase Auth users from your customers' directories, using Scalekit's SCIM webhooks and the Supabase admin API.

Your enterprise customers sign in to your app with SSO, and their IT teams now want to manage who has access from their directory, such as Okta or Microsoft Entra ID, instead of inviting and removing people by hand. With SCIM, the directory tells Scalekit about each change, Scalekit sends your app a webhook, and a small handler applies the change to Supabase Auth with the admin API.

By the end:

Users your customers add to their directory are created in Supabase, and their details stay in sync.
Users your customers deactivate are blocked in Supabase, so they can’t sign in or refresh their session. Reactivated users are unblocked.

To also let these users sign in through their company’s identity provider, see Add SSO to Supabase Auth.

Before you start

A Supabase project and its secret key (sb_secret_…) or legacy service role key. Run the handler on your server; never ship either key to a browser.
Your Scalekit environment URL, client ID and client secret, from Developers > Settings > API Credentials in the Scalekit dashboard.
An organization in Scalekit with a directory connected, and a webhook endpoint subscribed to the directory user events. Copy the endpoint’s signing secret (whsec_…). See Set up SCIM provisioning.

What Scalekit sends

Each change in the directory reaches your handler as one of three events:

Event	When
`organization.directory.user_created`	A user is added, or a deactivated user is reactivated.
`organization.directory.user_updated`	An active user’s details change.
`organization.directory.user_deleted`	A user is deactivated or removed.

Map directory users to Supabase users

The handler needs to know which Supabase user each directory user is. A table keeps that mapping. The first time the directory sends someone, a function looks for an existing Supabase user with the same email in the same Scalekit organization: someone who already signed in through that organization’s SSO connection, or someone the handler created for it before. The handler marks the users it creates in app_metadata, which only the admin API can change.

Anyone else with that email is left alone, such as a user who signed up with a password or one from another organization. Otherwise, someone who registered an employee’s email first could take over their account. In that case createUser fails with email_exists and the handler returns 500, so you can sort it out.

Run this SQL in the Supabase SQL Editor:

1
create table public.directory_users (
2
  directory_user_id text primary key,
3
  supabase_user_id uuid not null references auth.users (id) on delete cascade
4
);
5
alter table public.directory_users enable row level security;
6
revoke all on table public.directory_users from anon, authenticated;
7
grant select, insert, update on table public.directory_users to service_role;
8

9
create function public.organization_user_id_by_email(
10
  p_email text,
11
  p_organization_id text,
12
  p_directory_user_id text
13
)
14
returns uuid
15
language sql
16
stable
17
security definer
18
set search_path = ''
19
as $$
20
  select u.id
21
    from auth.users u
22
   where lower(u.email) = lower(p_email)
23
     and (
24
       -- Signed in through the organization's SSO connection
25
       exists (
26
         select 1 from auth.identities i
27
          where i.user_id = u.id
28
            and i.provider = 'custom:scalekit'
29
            and i.identity_data -> 'custom_claims' ->> 'oid' = p_organization_id
30
       )
31
       -- Created by the handler for the organization, for this directory user
32
       -- or one it replaced. Only the admin API can set app_metadata.
33
       or (
34
         u.raw_app_meta_data ->> 'organization_id' = p_organization_id
35
         and (
36
           u.raw_app_meta_data ->> 'directory_user_id' = p_directory_user_id
37
           or exists (select 1 from public.directory_users d where d.supabase_user_id = u.id)
38
         )
39
       )
40
     )
41
   limit 1;
42
$$;
43
revoke execute on function public.organization_user_id_by_email(text, text, text) from public, anon, authenticated;
44
grant execute on function public.organization_user_id_by_email(text, text, text) to service_role;

Run the webhook handler

The handler checks each webhook’s signature, then creates, updates or blocks the user:

1
import 'dotenv/config'
2
import express from 'express'
3
import { Scalekit } from '@scalekit-sdk/node'
4
import { createClient } from '@supabase/supabase-js'
5

6
const scalekit = new Scalekit(
7
  process.env.SCALEKIT_ENVIRONMENT_URL,
8
  process.env.SCALEKIT_CLIENT_ID,
9
  process.env.SCALEKIT_CLIENT_SECRET,
10
)
11
const supabase = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_SERVICE_ROLE_KEY)
12

13
// About 100 years: Supabase has no permanent ban, so use a very long one
14
const BLOCKED = '876000h'
15

16
async function findSupabaseUserId(directoryUser, organizationId) {
17
  const { data, error } = await supabase
18
    .from('directory_users')
19
    .select('supabase_user_id')
20
    .eq('directory_user_id', directoryUser.id)
21
    .maybeSingle()
22
  if (error) throw error
23
  if (data) return data.supabase_user_id
24

25
  // The user may already exist, for example because they signed in with SSO first
26
  const { data: id, error: rpcError } = await supabase.rpc('organization_user_id_by_email', {
27
    p_email: directoryUser.email,
28
    p_organization_id: organizationId,
29
    p_directory_user_id: directoryUser.id,
30
  })
31
  if (rpcError) throw rpcError
32
  return id
33
}
34

35
async function upsertUser(directoryUser, organizationId) {
36
  const attributes = {
37
    email: directoryUser.email,
38
    user_metadata: {
39
      given_name: directoryUser.given_name,
40
      family_name: directoryUser.family_name,
41
    },
42
    // Lets a retry find this user if saving the mapping below fails
43
    app_metadata: { organization_id: organizationId, directory_user_id: directoryUser.id },
44
  }
45

46
  let id = await findSupabaseUserId(directoryUser, organizationId)
47
  if (id) {
48
    // Also lifts the block on a user the directory reactivates
49
    const { error } = await supabase.auth.admin.updateUserById(id, {
50
      ...attributes,
51
      email_confirm: true,
52
      ban_duration: 'none',
53
    })
54
    if (error) throw error
55
  } else {
56
    const { data, error } = await supabase.auth.admin.createUser({
57
      ...attributes,
58
      email_confirm: true,
59
    })
60
    if (error) throw error
61
    id = data.user.id
62
  }
63

64
  const { error } = await supabase
65
    .from('directory_users')
66
    .upsert({ directory_user_id: directoryUser.id, supabase_user_id: id })
67
  if (error) throw error
68
}
69

70
async function blockUser(directoryUser, organizationId) {
71
  const id = await findSupabaseUserId(directoryUser, organizationId)
72
  if (!id) return
73
  const { error } = await supabase.auth.admin.updateUserById(id, { ban_duration: BLOCKED })
74
  if (error) throw error
75
}
76

77
async function handleEvent(event) {
78
  switch (event.type) {
79
    // Also sent when the directory reactivates a user
80
    case 'organization.directory.user_created':
81
      return upsertUser(event.data, event.organization_id)
82
    case 'organization.directory.user_updated':
83
      if (event.data.active === false) return blockUser(event.data, event.organization_id)
84
      return upsertUser(event.data, event.organization_id)
85
    // Also sent when the directory deactivates a user
86
    case 'organization.directory.user_deleted':
87
      return blockUser(event.data, event.organization_id)
88
  }
89
}
90

91
const app = express()
92

93
app.post('/webhooks/scalekit', express.raw({ type: 'application/json' }), async (req, res) => {
94
  const payload = req.body.toString()
95
  const headers = {
96
    'webhook-id': req.headers['webhook-id'],
97
    'webhook-timestamp': req.headers['webhook-timestamp'],
98
    'webhook-signature': req.headers['webhook-signature'],
99
  }
100

101
  try {
102
    scalekit.verifyWebhookPayload(process.env.SCALEKIT_WEBHOOK_SECRET, headers, payload)
103
  } catch {
104
    return res.status(401).json({ error: 'Invalid signature' })
105
  }
106

107
  try {
108
    await handleEvent(JSON.parse(payload))
109
    return res.status(200).json({ received: true })
110
  } catch (err) {
111
    console.error('Failed to process webhook:', err)
112
    return res.status(500).json({ error: 'Processing failed' })
113
  }
114
})
115

116
app.listen(3000, () => console.log('Listening on http://localhost:3000'))

Install the packages with npm install express @scalekit-sdk/node @supabase/supabase-js dotenv, add SCALEKIT_WEBHOOK_SECRET to your .env file, and run node scim-webhook.mjs.

Scalekit retries a webhook that fails, and the handler is safe to run twice, so a retry doesn’t create a second user. Blocking keeps the user’s data, and access tokens issued before the block stay valid until they expire. To delete users instead, call supabase.auth.admin.deleteUser(id) in blockUser.

Test provisioning

Expose the handler at a public URL, such as with a tunnel, and set that URL on your webhook endpoint in Scalekit.
Add a user to the directory, or assign them to the app in your IdP.

In the Supabase SQL Editor, look at the users the handler created:

select distinct u.email, u.raw_app_meta_data ->> 'organization_id' as organization_id, u.banned_until
from public.directory_users d
join auth.users u on u.id = d.supabase_user_id;

The new user has your Scalekit organization ID and an empty banned_until.

Deactivate the user in the directory. Their banned_until is now about 100 years in the future, and they can’t sign in.

Add SSO to Supabase Auth: let these users sign in through their company’s IdP.
Directory webhooks reference: the fields in the user events.