Skip to content

Interceptor triggers

The points in the authentication flow where Scalekit calls your interceptor endpoint

`PRE_SIGNUP`

Fires before a user creates a new organization. Use this to validate email domains, check against blocklists, or enforce custom signup policies.

Request body from Scalekit

1
{
2
  "display_name": "Validate email domain",
3
  "trigger_point": "PRE_SIGNUP",
4
  "interceptor_context": {
5
    "environment_id": "env_92561807201272162",
6
    "user_id": "usr_93418238346728951", // Present only if user exists in another organization
7
    "user_email": "john.doe@acmecorp.com", // Email attempting to sign up
8
    "connection_details": [
9
      {
10
        "id": "conn_92561808744978132",
11
        "type": "OAUTH", // OAUTH, SAML, OIDC, or PASSWORDLESS
12
        "provider": "GOOGLE" // Identity provider used for authentication
13
      }
14
    ],
15
    //Contains parameters from the /oauth/authorize request
16
    "auth_request": {
17
        "connection_id": "conn_81665025441299343",
18
        "organization_id": "org_102953846317318346",
19
        "domain": "foocorp.com",
20
        "login_hint": "john.doe@example.com",
21
        "state": "xsrPHl7k7ARgdhC6"
22
    },
23
    "device_type": "Desktop", // Desktop, Mobile, Tablet, or Unknown
24
    "ip_address": "203.0.113.24", // Client's IP address for geolocation or blocklist checks
25
    "region": "IN", // Two-letter country code
26
    "city": "Bengaluru",
27
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36...",
28
    "triggered_at": "2025-10-09T09:48:02.875Z" // ISO 8601 timestamp
29
  },
30
  "data": {
31
    // User object present only when user already exists in another organization
32
    "user": {
33
      "id": "usr_93418238346728951",
34
      "name": "John Doe",
35
      "email": "john.doe@acmecorp.com",
36
      "email_verified": true,
37
      "created_at": "2025-10-06T11:06:49.120Z",
38
      "updated_at": "2025-10-06T13:33:06.479Z",
39
      "given_name": "John",
40
      "family_name": "Doe",
41
      "metadata": {
42
        "type": "social_user"
43
      },
44
      "memberships": [ // Existing organization memberships
45
        {
46
          "organization_id": "org_93418204671239864",
47
          "status": "ACTIVE",
48
          "roles": [
49
              "admin"
50
          ],
51
          "metadata": {
52
                "cost": {
53
                    "category": "platform",
54
                    "region": "US"
55
                },
56
                "department": "engineering"
57
          },
58
           "organization_name": "Example inc"
59
        }
60
      ]
61
    }
62
  }
63
}

Response format to return

1
{
2
  // Required: choose ALLOW or DENY
3
  "decision": "DENY", // ALLOW | DENY
4
  // Optional with DENY
5
  "error": {
6
    "message": "Only @acmecorp.com email addresses are allowed to sign up" // Shown to user when DENY
7
  },
8
  // Optional with ALLOW, Include when the user is to be provisioned in an existing organization.
9
   "response": {
10
        "create_organization_membership": {
11
            // either external_organization_id or organization_id is required
12
            "external_organization_id": "ext_B6YycAGRaPmnuxAFPT5KI4HBHxr4qWX",
13
            "organization_id": "org_102953846317318346",
14
            "roles": [
15
                "admin",
16
                "viewer"
17
            ]
18
        }
19
    }
20
}

`PRE_SESSION_CREATION`

Fires before session tokens are issued for a user. Use this to add custom claims to tokens, apply conditional access policies, or integrate with external authorization systems.

Request body from Scalekit

1
{
2
  "display_name": "Add custom claims to tokens",
3
  "trigger_point": "PRE_SESSION_CREATION",
4
  "interceptor_context": {
5
    "environment_id": "env_92561807204567213",
6
    "user_id": "usr_93418238346728951",
7
    "user_email": "john.doe@acmecorp.com",
8
    "organization_id": "org_93418204671239864", // Organization user is logging into
9
    "connection_details": [
10
      {
11
        "id": "conn_92561808744978132",
12
        "type": "OAUTH", // Authentication method used
13
        "provider": "GOOGLE"
14
      }
15
    ],
16
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36...",
17
    "device_type": "Desktop", // Desktop, Mobile, Tablet, or Unknown
18
    "ip_address": "203.0.113.24", // Use for conditional access based on location
19
    "region": "US", // Two-letter country code
20
    "city": "San Francisco",
21
    "triggered_at": "2025-10-08T15:22:42.381Z" // ISO 8601 timestamp
22
  },
23
  "data": {
24
    "user": {
25
      "id": "usr_93418238346728951",
26
      "name": "John Doe",
27
      "email": "john.doe@acmecorp.com",
28
      "email_verified": true,
29
      "created_at": "2025-10-06T11:06:49.120Z",
30
      "updated_at": "2025-10-06T13:33:06.479Z",
31
      "first_name": "John",
32
      "last_name": "Doe",
33
      "memberships": [ // All organizations this user belongs to
34
        {
35
          "organization_id": "org_93418204671239864",
36
          "status": "ACTIVE"
37
        }
38
      ]
39
    }
40
  }
41
}

Response format to return

1
{
2
  "decision": "ALLOW", // Required: ALLOW to issue tokens, DENY to block login
3
  "response": {
4
    "claims": { // Optional: Custom claims added to both access and ID tokens
5
      "subscription_tier": "enterprise",
6
      "data_region": "us-west-2",
7
      "feature_flags": ["analytics_dashboard", "api_access", "custom_branding"],
8
      "account_manager": "jane.smith@acmecorp.com"
9
    }
10
  }
11
}

`PRE_USER_INVITATION`

Fires before an invitation is created or sent for a new organization member. Use this to validate invitee email addresses, enforce invitation policies, or check user limits.

Request body from Scalekit

1
{
2
    "display_name": "Validate invitation policy",
3
    "trigger_point": "PRE_USER_INVITATION",
4
    "interceptor_context": {
5
        "environment_id": "env_92561807201272162",
6
        "user_id": "usr_93418238346728951", // Present only if invitee already exists in another org
7
        "user_email": "sarah.johnson@contractor.com", // Email address being invited
8
        "organization_id": "org_93731871904672153", // Organization sending the invitation
9
        "city": "Bengaluru",
10
        "device_type": "Desktop", // Device of the person sending the invitation
11
        "ip_address": "182.156.5.2", // IP of the person sending the invitation
12
        "region": "IN", // Two-letter country code
13
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36...",
14
        "triggered_at": "2025-10-09T12:50:41.803Z" // ISO 8601 timestamp
15
    },
16
    "data": {
17
        "organization": { // Organization details for context
18
            "id": "org_93731871904672153",
19
            "name": "Acme Corp"
20
        }
21
    }
22
}

Response format to return

1
{
2
  "decision": "DENY", // Required: ALLOW to send invitation, DENY to block
3
  "error": {
4
    "message": "Cannot invite users from external domains. Please use @acmecorp.com email addresses." // Shown when DENY
5
  }
6
}

`PRE_M2M_TOKEN_CREATION`

Fires before issuing a machine-to-machine access token. Use this to add custom claims, modify scopes dynamically, or apply conditional access rules for service-to-service authentication.

Request body from Scalekit

1
{
2
  "display_name": "Validate M2M client permissions",
3
  "trigger_point": "PRE_M2M_TOKEN_CREATION",
4
  "interceptor_context": {
5
    "environment_id": "env_17002334043308132",
6
    "client_id": "m2morg_93710427703245914", // M2M client requesting the token
7
    "user_agent": "deployment-service/2.1.0", // Service making the request
8
    "device_type": "Unknown",
9
    "triggered_at": "2025-10-08T21:22:20.173Z" // ISO 8601 timestamp
10
  },
11
  "data": {
12
    "m2m_token_claims": { // Claims that will be included in the token
13
      "client_id": "m2morg_93710427703245914",
14
      "claims": {
15
        "custom_claims": { // Existing custom claims from client configuration
16
          "service_name": "deployment-automation",
17
          "deployment_environment": "production"
18
        },
19
        "oid": "org_89669394174574792", // Organization ID for this M2M client
20
        "scope": "deploy:applications read:deployments write:logs", // Space-separated scopes
21
        "scopes": [ // Array of individual scopes requested
22
          "deploy:applications",
23
          "read:deployments",
24
          "write:logs"
25
        ]
26
      }
27
    }
28
  }
29
}

Response format to return

1
{
2
  "decision": "ALLOW", // Required: ALLOW to issue token, DENY to block
3
  "response": {
4
    "claims": { // Optional: Add or modify claims in the M2M token
5
      "scope": "deploy:applications read:deployments", // Can modify scopes dynamically
6
      "aud": "https://api.acmecorp.com", // Target audience for the token
7
      "rate_limit": "1000", // Custom claim for rate limiting
8
      "environment": "production" // Custom claim for environment context
9
    }
10
  }
11
}