The Single Sign-On Teammates API allows you to add and modify SSO Teammates over Subusers.
SSO Teammates are the individual user accounts who will access your Twilio SendGrid account with SSO credentials.
Endpoint overview:
POST/v3/sso/teammates
Base url: https://api.sendgrid.com
This endpoint allows you to create an SSO Teammate.
The email address provided for the Teammate will also function as the Teammate's username. Once created, the Teammate's email address cannot be changed.
Scopes:
When creating a Teammate, you will assign it permissions or scopes. These scopes determine which actions the Teammate can perform and which features they can access. Scopes are provided with one of three properties passed to this endpoint: is_admin and scopes
You can make a Teammate an administrator by setting is_admin to true. Administrators will have all scopes assigned to them.
You can assign individual permissions with the scopes property.
Subuser access:
SendGrid SSO Teammates may be assigned access to one or more Subusers. Subusers function like SendGrid sub-accounts with their own resources.
When assigning Subuser access to an SSO Teammate, you may set the has_restricted_subuser_access property to true to constrain the Teammate so that they can operate only on behalf of the Subusers to which they are assigned.
You may further set the level of access the Teammate has to each Subuser with the subuser_access property.
has_restricted_subuser_access :
Set this property to true to give the Teammate permissions to operate only on behalf of a Subuser. This property value must be true if the subuser_access property is not empty. The subuser_access property determines which Subusers the Teammate may act on behalf of. If this property is set to true, you cannot specify individual scopes or set is_admin to true (a Teammate cannot specify scopes for the account and have restricted Subuser access.)
subuser_access :
Specify which Subusers the Teammate may access and act on behalf of with this property.
id :
Set this property to the ID of a Subuser to which the Teammate should have access.
permission_type :
Grant the level of access the Teammate should have to the specified Subuser with this property.
This property value may be either admin or restricted.
When set to restricted, the Teammate has only the permissions assigned in the scopes property.
scopes :
Add or remove permissions that the Teammate can access on behalf of the Subuser.
You should not include this property in the request when the permission_type property is set to admin as administrators have full access to the specified Subuser.
persona is currently not available under Teammate setup due to the new scopes updated under "permission_type": "restricted" for Subuser SSO teammates
These are the new available scopes when has_restricted_subuser_access property is set to true
"scopes": [
"access_settings.activity.read",
"access_settings.whitelist.create",
"access_settings.whitelist.delete",
"access_settings.whitelist.read",
"access_settings.whitelist.update",
"alerts.create",
"alerts.delete",
"alerts.read",
"alerts.update",
"api_keys.create",
"api_keys.delete",
"api_keys.read",
"api_keys.update",
"asm.groups.create",
"asm.groups.delete",
"asm.groups.read",
"asm.groups.suppressions.create",
"asm.groups.suppressions.delete",
"asm.groups.suppressions.read",
"asm.groups.suppressions.update",
"asm.groups.update",
"asm.suppressions.global.create",
"asm.suppressions.global.delete",
"asm.suppressions.global.read",
"asm.suppressions.global.update",
"browsers.stats.read",
"categories.create",
"categories.delete",
"categories.read",
"categories.stats.read",
"categories.stats.sums.read",
"categories.update",
"clients.desktop.stats.read",
"clients.phone.stats.read",
"clients.stats.read",
"clients.tablet.stats.read",
"clients.webmail.stats.read",
"credentials.create",
"credentials.delete",
"credentials.read",
"credentials.update",
"design_library.create",
"design_library.delete",
"design_library.read",
"design_library.update",
"devices.stats.read",
"di.bounce_block_classification.read",
"email_testing.read",
"email_testing.write",
"geo.stats.read",
"ips.assigned.read",
"ips.pools.create",
"ips.pools.delete",
"ips.pools.ips.create",
"ips.pools.ips.delete",
"ips.pools.ips.read",
"ips.pools.ips.update",
"ips.pools.read",
"ips.pools.update",
"ips.warmup.create",
"ips.warmup.delete",
"ips.warmup.read",
"ips.warmup.update",
"mail.batch.create",
"mail.batch.delete",
"mail.batch.read",
"mail.batch.update",
"mail.send",
"mail_settings.address_whitelist.create",
"mail_settings.address_whitelist.delete",
"mail_settings.address_whitelist.read",
"mail_settings.address_whitelist.update",
"mail_settings.bcc.create",
"mail_settings.bcc.delete",
"mail_settings.bcc.read",
"mail_settings.bcc.update",
"mail_settings.bounce_purge.create",
"mail_settings.bounce_purge.delete",
"mail_settings.bounce_purge.read",
"mail_settings.bounce_purge.update",
"mail_settings.footer.create",
"mail_settings.footer.delete",
"mail_settings.footer.read",
"mail_settings.footer.update",
"mail_settings.forward_bounce.create",
"mail_settings.forward_bounce.delete",
"mail_settings.forward_bounce.read",
"mail_settings.forward_bounce.update",
"mail_settings.forward_spam.create",
"mail_settings.forward_spam.delete",
"mail_settings.forward_spam.read",
"mail_settings.forward_spam.update",
"mail_settings.plain_content.create",
"mail_settings.plain_content.delete",
"mail_settings.plain_content.read",
"mail_settings.plain_content.update",
"mail_settings.read",
"mail_settings.spam_check.create",
"mail_settings.spam_check.delete",
"mail_settings.spam_check.read",
"mail_settings.spam_check.update",
"mail_settings.template.create",
"mail_settings.template.delete",
"mail_settings.template.read",
"mail_settings.template.update",
"mailbox_providers.stats.read",
"marketing_campaigns.create",
"marketing_campaigns.delete",
"marketing_campaigns.read",
"marketing_campaigns.update",
"marketing.read",
"marketing.automation.read",
"messages.read",
"partner_settings.new_relic.create",
"partner_settings.new_relic.delete",
"partner_settings.new_relic.read",
"partner_settings.new_relic.update",
"partner_settings.read",
"partner_settings.sendwithus.create",
"partner_settings.sendwithus.delete",
"partner_settings.sendwithus.read",
"partner_settings.sendwithus.update",
"recipients.erasejob.create",
"recipients.erasejob.read",
"stats.global.read",
"stats.read",
"suppression.blocks.create",
"suppression.blocks.delete",
"suppression.blocks.read",
"suppression.blocks.update",
"suppression.bounces.create",
"suppression.bounces.delete",
"suppression.bounces.read",
"suppression.bounces.update",
"suppression.create",
"suppression.delete",
"suppression.invalid_emails.create",
"suppression.invalid_emails.delete",
"suppression.invalid_emails.read",
"suppression.invalid_emails.update",
"suppression.read",
"suppression.spam_reports.create",
"suppression.spam_reports.delete",
"suppression.spam_reports.read",
"suppression.spam_reports.update",
"suppression.unsubscribes.create",
"suppression.unsubscribes.delete",
"suppression.unsubscribes.read",
"suppression.unsubscribes.update",
"suppression.update",
"templates.create",
"templates.delete",
"templates.read",
"templates.update",
"templates.versions.activate.create",
"templates.versions.activate.delete",
"templates.versions.activate.read",
"templates.versions.activate.update",
"templates.versions.create",
"templates.versions.delete",
"templates.versions.read",
"templates.versions.update",
"tracking_settings.click.create",
"tracking_settings.click.delete",
"tracking_settings.click.read",
"tracking_settings.click.update",
"tracking_settings.google_analytics.create",
"tracking_settings.google_analytics.delete",
"tracking_settings.google_analytics.read",
"tracking_settings.google_analytics.update",
"tracking_settings.open.create",
"tracking_settings.open.delete",
"tracking_settings.open.read",
"tracking_settings.open.update",
"tracking_settings.read",
"tracking_settings.subscription.create",
"tracking_settings.subscription.delete",
"tracking_settings.subscription.read",
"tracking_settings.subscription.update",
"user.account.read",
"user.credits.read",
"user.email.read",
"user.scheduled_sends.create",
"user.scheduled_sends.delete",
"user.scheduled_sends.read",
"user.scheduled_sends.update",
"user.settings.enforced_tls.read",
"user.settings.enforced_tls.update",
"user.timezone.create",
"user.timezone.delete",
"user.timezone.read",
"user.timezone.update",
"user.username.read",
"user.webhooks.event.settings.create",
"user.webhooks.event.settings.delete",
"user.webhooks.event.settings.read",
"user.webhooks.event.settings.update",
"user.webhooks.event.test.create",
"user.webhooks.event.test.delete",
"user.webhooks.event.test.read",
"user.webhooks.event.test.update",
"user.webhooks.parse.settings.create",
"user.webhooks.parse.settings.delete",
"user.webhooks.parse.settings.read",
"user.webhooks.parse.settings.update",
"user.webhooks.parse.stats.read",
"whitelabel.create",
"whitelabel.delete",
"whitelabel.read",
"whitelabel.update"
]
Example Payload to setup Restricted Subuser Access:
{
"email": "SsoSubuser.Restrict@example.com",
"first_name": "SsoSubuser",
"last_name": "Restrict",
"is_admin": false,
"is_sso": true,
"has_restricted_subuser_access": true,
"subuser_access": [
{
"id":12345678,
"permission_type": "restricted",
"scopes": [
<add new available scopes here>
]
},
{
"id":87654321,
"permission_type": "restricted",
"scopes": [
<add new available scopes here>
]
}
]
}
Example Response :
{
"username": "SsoSubuser.Restrict@example.com",
"first_name": "SsoSubuser",
"last_name": "Restrict",
"email": "SsoSubuser.Restrict@example.com",
"is_admin": false,
"is_read_only": false,
"is_sso": true,
"subuser_access": [
{
"id": 12345678,
"username": "subuser_staging",
"email": "staging@example.com",
"disabled": false,
"permission_type": "restricted",
"scopes": [
<Scopes added on the payload will be listed here>
]
},
{
"id": 87654321,
"username": "subuser_prod",
"email": "prod@example.com",
"disabled": false,
"permission_type": "restricted",
"scopes": [
<Scopes added on the payload will be listed here>
]
}
],
"has_restricted_subuser_access": true
}
Reference links :
Troubleshooting :
In the event of access/permission errors following the selection of updated scopes within restricted access, please collect the following details for Support
- GET response of the scopes assigned to the SSO teammate with restricted subuser access
- Initiate and capture a SAML trace during teammate login to subuser via SSO
- Capture a screenshot of Account details which contains the username and email
- Access the tabs on SendGrid which the SSO teammate which shouldn't have access to and Initiate a HAR capture prior to clicking on these tabs