SendGrid Teammates Integration

Scimify enables SCIM provisioning for SendGrid teammates, allowing you to invite users and manage teammate admin status and permission scopes through your identity provider.

Overview

This integration (de)provisions teammates on a single SendGrid parent account using the Teammates API. Scimify accepts standard SCIM requests from your IdP and translates them into teammate invite, permission update, and delete API calls.

Key behaviors:

User-only — no group provisioning
Invite-based provisioning — new users are invited as teammates (they must accept before they are active)
Permission management — optional sendgrid_is_admin and sendgrid_scopes SCIM attributes map to SendGrid teammate permissions
Deprovisioning — removing access deletes the teammate or cancels a pending invite (hard delete)

Out of scope: SendGrid Subusers (isolated child accounts) are not managed by this connector. Use a separate integration if Subuser provisioning is required later.

Prerequisites

A SendGrid account with permission to manage teammates
An API key with Custom Access and Teammates set to Full Access (see below)
Your IdP or identity governance platform (IGA) configured for SCIM provisioning (see SCIM Configuration)

Note: Free and Essentials plans allow one teammate per account. Pro and higher plans allow up to 1,000 teammates. See SendGrid pricing.

For API details, see the Teammates API reference and Teammates UI guide.

Configuration Steps

1. Create a SendGrid API Key

Follow least privilege: use Custom Access, not Full Access, and grant only what Scimify needs to manage teammates.

Sign in to the SendGrid app
Open API Keys under Settings
Click Create API Key
Enter a name (for example, Scimify Teammates)
Under API Key Permissions, select Restricted Access (Custom Access)
Find Teammates and set its access slider to Full Access
Leave other permission categories at No Access unless you intentionally need them for other purposes
Click Create & View, then copy the key and store it securely — SendGrid shows the full key only once

Use a dedicated API key for Scimify so you can rotate or revoke it without affecting other automations.

2. Configure the Integration in Scimify

Navigate to the Integrations page in your Scimify admin console
Create a new SendGrid Teammates integration instance
Set an instance display name (for example, Production SendGrid) so you can distinguish multiple connections
Enter your API Key
Save the configuration and use Test connection to verify API access
Enable the integration and copy the Scimify SCIM endpoint and API key for your IdP

Only the API key is required in the integration config. Your SendGrid account is determined by the API key; no separate hostname is required.

3. Configure Teammate Permissions (Optional)

To assign admin status or granular scopes via SCIM, add the custom attributes described below to your IdP user profile and map them into the SCIM user payload.

SendGrid’s invite UI offers Admin, Read-only, and Restricted (custom scopes). Scimify maps those as follows when attributes are omitted:

Attribute	Default
`sendgrid_is_admin`	`false`
`sendgrid_scopes`	Read-only scope set (invite-safe subset of Observer / UI Read Access)

Empty sendgrid_scopes for a non-admin invite is not accepted by SendGrid (scopes cannot be empty), so Scimify applies the Read-only default instead of sending [].

This integration uses the non-SSO Teammates API (POST /v3/teammates). The SSO Observer persona is a useful reference for Read-only access, but Scimify does not send the full Observer list on invite because:

Billing scopes are mutually exclusive with all other scopes (Teammate permissions)
Some scopes cannot be assigned on invite (for example user.profile.update)
Some scopes are plan- or add-on-gated (for example Subusers, Email Testing, dedicated IPs)

To invite an Admin teammate, set sendgrid_is_admin=true (scopes are sent empty). To invite with Restricted / custom access, set sendgrid_is_admin=false and provide the desired sendgrid_scopes list.

4. Configure SCIM in your IdP or IGA

Follow the SCIM Configuration guide to connect Okta or Lumos to your Scimify SendGrid Teammates instance, then assign users as needed.

How It Works

User Provisioning

When a user is assigned in your IdP:

Scimify checks whether the email already exists as an accepted teammate
If not, Scimify checks for an existing pending invite for that email
If neither exists, Scimify creates a new teammate invite with the requested sendgrid_is_admin and sendgrid_scopes

The invited user must accept the invite (and complete SendGrid onboarding) before they appear as an active teammate. Invites expire after 7 days.

User Updates

Active teammates — permission changes are applied with PATCH /v3/teammates/{username} (is_admin and scopes)
Pending invites — SendGrid does not support updating an invite in place; Scimify deletes the pending invite and creates a new invite when permissions change
Profile fields — first name, last name, and email are not updated through this integration after invite
sendgrid_user_type — returned by SendGrid (admin, owner, or teammate) and treated as read-only; it is not settable on invite or update

User Deprovisioning

When a user is unassigned or deactivated in your IdP:

Active teammates are deleted from the account
Pending invites are deleted

This is a hard remove (not a soft disable). Deleted teammates cannot be restored in SendGrid.

Custom SCIM Attribute Configuration

Configure the following custom attributes under the shared extension schema
urn:ietf:params:scim:schemas:extension:custom:2.0:User.

Attribute: sendgrid_is_admin

Setting	Value
Type	Boolean
External namespace	`urn:ietf:params:scim:schemas:extension:custom:2.0:User`
Attribute name	`sendgrid_is_admin`
Description	Whether the teammate should have admin privileges
Default	`false` (if not sent in SCIM)

When sendgrid_is_admin is true, Scimify sends an empty scopes array (required by SendGrid for admin teammates).

Attribute: sendgrid_scopes

Setting	Value
Type	String (multi-valued)
External namespace	`urn:ietf:params:scim:schemas:extension:custom:2.0:User`
Attribute name	`sendgrid_scopes`
Description	List of SendGrid permission scopes for a non-admin teammate
Default	Invite-safe Read-only scope set when omitted or empty

When omitted (or empty) and sendgrid_is_admin is false, Scimify applies a Read-only scope set suitable for non-SSO teammate invites. It is derived from the Observer / UI Read Access model in Teammate permissions, with billing, invite-unassignable, and common plan-gated scopes removed.

Examples of custom (Restricted) scopes include mail.send, stats.read, and other values from Teammate permissions. Do not mix billing.* with other scopes. Invalid or unassignable scopes are rejected by the SendGrid API.

Attribute: sendgrid_user_type (read-only)

Setting	Value
Type	String
External namespace	`urn:ietf:params:scim:schemas:extension:custom:2.0:User`
Attribute name	`sendgrid_user_type`
Description	Teammate type returned by SendGrid
Mutability	Read-only

Values returned by SendGrid:

Value	Description
`owner`	Account owner
`admin`	Admin teammate
`teammate`	Restricted / non-admin teammate

Do not rely on writing sendgrid_user_type via SCIM. Use sendgrid_is_admin (and sendgrid_scopes when not admin) to control access.

Scimify accepts writable attributes in any of these common SCIM shapes:

Top-level field: sendgrid_is_admin / sendgrid_scopes
Extension key: urn:ietf:params:scim:schemas:extension:custom:2.0:User:sendgrid_is_admin
Nested extension object: urn:ietf:params:scim:schemas:extension:custom:2.0:User → { "sendgrid_is_admin": false, "sendgrid_scopes": ["mail.send"] }

Suggested Okta profile attributes

In Okta, add user profile attributes for your SendGrid Teammates SCIM app:
- sendgrid_is_admin — boolean; External namespace urn:ietf:params:scim:schemas:extension:custom:2.0:User; External name sendgrid_is_admin
- sendgrid_scopes — string array (or string you map to a multi-valued SCIM attribute); External name sendgrid_scopes
Map the attributes in the Okta → Scimify provisioning profile so they are included on create and update
Optionally import sendgrid_user_type as a read-only attribute for reporting

Mapping guidance

Default most users to sendgrid_is_admin=false with the minimum scopes they need
Use group rules or entitlements to grant admin only to a small set of operators
Prefer least-privilege scopes; if sendgrid_scopes is omitted, Scimify defaults to an invite-safe Read-only set (not Admin, and not the full SSO Observer persona list)
Billing scopes are mutually exclusive — do not combine billing.* with other scopes in sendgrid_scopes

Limitations and Behavior Notes

Invite-based create — SCIM “create user” invites a teammate; users are not fully active until they accept
Pending invite tracking — Scimify stores invite tokens (prefixed as invite-…) until acceptance; lookups reconcile invite vs username IDs on refresh
No group support — this connector does not create or sync groups
No soft disable — deprovision deletes the teammate or pending invite
No profile rename — name and email are not updated after invite via this integration
No Subusers — Subuser accounts are out of scope
Plan limits — Free/Essentials allow one teammate; Pro+ allow more (see SendGrid plan limits)
Owner protection — do not attempt to delete the account owner via SCIM; SendGrid will reject unsafe operations

Troubleshooting

Authentication failed (401)
- Confirm the API key is correct and active in SendGrid API key settings
- Regenerate the key and update the Scimify integration config
Access forbidden (403)
- Ensure the API key uses Restricted Access with the Teammates slider set to Full Access
Bad request / invalid scopes
- Confirm sendgrid_scopes values are valid SendGrid scopes for your plan
- When sendgrid_is_admin is true, scopes must be empty
- When sendgrid_is_admin is false, scopes cannot be empty — omit the attribute to use the Read-only default, or supply an explicit Restricted scope list
- Do not mix billing.* with other scopes (mutually exclusive)
- Do not include invite-unassignable scopes such as user.profile.update on create
User already exists
- Scimify returns the existing teammate or pending invite ID; this is expected idempotent behavior
Invite expired
- Pending invites expire after 7 days; re-assign or update the user in your IdP to create a fresh invite
User not removed after deprovision
- Verify the user was unassigned from the IdP SCIM app and provisioning ran successfully
- Check Scimify audit logs for teammate delete vs invite-delete operations

Additional Resources

Need Help?

If you encounter issues configuring sendgrid_is_admin / sendgrid_scopes mappings or API key permissions, contact [email protected] for assistance.