Custom Access Token Hook
Customize the access token issued by Supabase Auth
The custom access token hook runs before a token is issued and allows you to add additional claims based on the authentication method used.
Claims returned must conform to our specification. Supabase Auth will check for these claims after the hook is run and return an error if they are not present.
These are the fields currently available on an access token:
Required Claims: iss, aud, exp, iat, sub, role, aal, session_id
Optional Claims: jti, nbf, app_metadata, user_metadata, amr, email, phone
Inputs
| Field | Type | Description |
|---|---|---|
user_id | string | Unique identifier for the user attempting to sign in. |
claims | object | Claims which are included in the access token. |
authentication_method | string | The authentication method used to request the access token. Possible values include: oauth, password, otp, totp, recovery, invite, sso/saml, magiclink, email/signup, email_change, token_refresh, anonymous. |
_19{_19 "user_id": "8ccaa7af-909f-44e7-84cb-67cdccb56be6",_19 "claims": {_19 "aud": "authenticated",_19 "exp": 1715690221,_19 "iat": 1715686621,_19 "sub": "8ccaa7af-909f-44e7-84cb-67cdccb56be6",_19 "email": "",_19 "phone": "",_19 "app_metadata": {},_19 "user_metadata": {},_19 "role": "authenticated",_19 "aal": "aal1",_19 "amr": [ { "method": "anonymous", "timestamp": 1715686621 } ],_19 "session_id": "4b938a09-5372-4177-a314-cfa292099ea2",_19 "is_anonymous": true_19 },_19 "authentication_method": "anonymous"_19}
Outputs
Return these only if your hook processed the input without errors.
| Field | Type | Description |
|---|---|---|
claims | object | The updated claims after the hook has been run. |
Sometimes the size of the JWT can be a problem especially if you're using a Server-Side Rendering framework. Common situations where the JWT can get too large include:
- The user has a particularly large name, email address or phone number
- The default JWT has too many claims coming from OAuth providers
- A large avatar URL is included
To lower the size of the JWT you can define a Custom Access Token hook like the one below which will instruct the Auth server to issue a JWT with only the listed claims. Check the documentation above on what JWT claims must be present and cannot be removed.
Refer to the Postgres JSON functions on how to manipulate jsonb objects.
_32create or replace function public.custom_access_token_hook(event jsonb)_32returns jsonb_32language plpgsql_32as $$_32 declare_32 original_claims jsonb;_32 new_claims jsonb;_32 claim text;_32 begin_32 original_claims = event->'claims';_32 new_claims = '{}'::jsonb;_32_32 foreach claim in array array[_32 -- add claims you want to keep here_32 'iss',_32 'aud',_32 'exp',_32 'iat',_32 'sub',_32 'role',_32 'aal',_32 'session_id'_32 ] loop_32 if original_claims ? claim then_32 -- original_claims contains one of the listed claims, set it on new_claims_32 new_claims = jsonb_set(new_claims, array[claim], original_claims->claim);_32 end if;_32 end loop;_32_32 return jsonb_build_object('claims', new_claims);_32 end_32$$;