Single Sign-On Teammates
The Single Sign-On APIs allow you to manage your SAML 2.0 SSO configurations. You can also work with your SSO integrations using the SSO section of the Twilio SendGrid App.
The Single Sign-On Teammates API allows you to add and modify SSO Teammates. SSO Teammates are the individual user accounts who will access your Twilio SendGrid account with SSO credentials.
To retrieve or delete an SSO Teammate, you will use the Teammates API.
For more information about managing SSO Teammates, see the Twilio SendGrid SSO documentation.
Create SSO Teammate
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, scopes, and persona.
You can make a Teammate an administrator by setting is_admin to true. Administrators will have all scopes assigned to them. Alternatively, you can assign a persona to the teammate, which will assign them a block of permissions commonly required for that type of user. See the "Persona scopes" section of Teammate Permissions for a list of permsissions granted by persona. Lastly, you can assign individual permissions with the scopes property. See Teammate Permissions for a full list of scopes that can be assigned to a Teammate.
Subuser access
SendGrid Teammates may be assigned access to one or more Subusers. Subusers function like SendGrid sub-accounts with their own resources. See Subusers for more information.
When assigning Subuser access to a 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.
Request Body
Set this property to the Teammate's email address. This email address will also function as the Teammate's username and must match the address assigned to the user in your IdP. This address cannot be changed after the Teammate is created.
format: emailSet this property to the Teammate's first name.
Set this property to the Teammate's last name.
Set this property to true if the Teammate has admin permissions. You should not include the scopes or persona properties when setting the is_admin property to true—an admin will be allocated all scopes. See Teammate Permissions for a complete list of scopes.
A persona represents a group of permissions often required by a type of Teammate such as a developer or marketer. Assigning a persona allows you to allocate a group of pre-defined permissions rather than assigning each scope individually. See Teammate Permissions for a full list of the scopes assigned to each persona.
Allowed Values: accountant, developer, marketer, observerAdd or remove permissions from a Teammate using this scopes property. See Teammate Permissions for a complete list of available scopes. You should not include this propety in the request when using the persona property or when setting the is_admin property to true—assigning a persona or setting is_admin to true will allocate a group of permissions to the Teammate.
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, assign a persona, or set is_admin to true—a Teammate cannot specify scopes for the parent account and have restricted Subuser access.
Specify which Subusers the Teammate may access and act on behalf of with this property. If this property is populated, you must set the has_restricted_subuser_access property to true.
Set this property to the ID of a Subuser to which the Teammate should have access. You can retrieve Subuser IDs from the Subusers API.
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.
Add or remove permissions that the Teammate can access on behalf of the Subuser. See Teammate Permissions for a complete list of available scopes. You should not include this property in the request when the permission_type property is set to admin—administrators have full access to the specified Subuser.
{
"email": "jane_doe@example.com",
"first_name": "Jane",
"last_name": "Doe",
"is_admin": false,
"has_restricted_subuser_access": true,
"subuser_access": [
{
"id": 12345,
"permission_type": "restricted",
"scopes": [
"alerts.read",
"asm.groups.read",
"billing.read",
"ips.warmup.read",
"ips.pools.read",
"ips.pools.ips.read",
"ips.assigned.read",
"ips.read",
"mail_settings.read",
"mail_settings.bcc.read",
"mail_settings.address_whitelist.read",
"mail_settings.footer.read",
"mail_settings.forward_spam.read",
"mail_settings.plain_content.read",
"mail_settings.spam_check.read",
"mail_settings.bounce_purge.update",
"mail_settings.forward_bounce.read",
"partner_settings.read",
"partner_settings.new_relic.read",
"partner_settings.sendwithus.read",
"tracking_settings.read",
"tracking_settings.click.read",
"tracking_settings.subscription.read",
"tracking_settings.open.read",
"tracking_settings.google_analytics.read",
"user.webhooks.event.settings.read",
"user.webhooks.event.test.read",
"user.webhooks.parse.settings.read",
"stats.read",
"stats.global.read",
"categories.stats.read",
"categories.stats.sums.read",
"devices.stats.read",
"clients.stats.read",
"clients.phone.stats.read",
"clients.tablet.stats.read",
"clients.webmail.stats.read",
"clients.desktop.stats.read",
"geo.stats.read",
"mailbox_providers.stats.read",
"browsers.stats.read",
"subusers.stats.read",
"subusers.stats.sums.read",
"subusers.stats.monthly.read",
"user.webhooks.parse.stats.read",
"subusers.read",
"subusers.monitor.read",
"subusers.credits.read",
"subusers.credits.remaining.read",
"subusers.reputations.read",
"subusers.summary.read",
"templates.read",
"templates.versions.read",
"user.account.read",
"user.credits.read",
"user.email.read",
"user.profile.read",
"user.profile.update",
"user.timezone.read",
"user.username.read",
"user.settings.enforced_tls.read",
"api_keys.read",
"categories.read",
"mail_settings.template.read",
"mail.batch.read",
"user.scheduled_sends.read",
"access_settings.whitelist.read",
"access_settings.activity.read",
"suppression.read",
"messages.read",
"email_testing.read",
"sender_verification_eligible",
"sender_verification_legacy",
"2fa_exempt",
"2fa_required"
]
}
]
}Responses
Successful SSO Teammates POST Response.
The Teammate's first name.
The Teammate's last name.
Teammate's email address. This email address also functions as the Teammate's username and must match the address assigned to the user in your IdP. This address cannot be changed after the Teammate is created.
format: emailIndicates if the Teammate has administrator permissions. When set to true, the Teammate is an admin.
Indicates how the Teammate authenticates with SendGrid. When set to true, the Teammate will access SendGrid via SSO and their IdP. When set to false, the Teammate will authenticate directly with SendGrid via a username and password.
The permissions or scopes currently assigned to the Teammate. See Teammate Permissions for a complete list of available scopes.
When this property is set to true, the Teammate has permissions to operate only on behalf of a Subuser. This property value is true when the subuser_access property is not empty. The subuser_access property determines which Subusers the Teammate may act on behalf of.
Specifies which Subusers the Teammate may access and act on behalf of. If this property is populated, the has_restricted_subuser_access property will be true.
The ID of a Subuser to which the Teammate has access. You can retrieve Subuser IDs from the Subusers API.
The username of a Subuser to which the Teammate has access.
The email address of a Subuser to which the Teammate has access.
Indicates if the Subuser is active for the SendGrid account.
The level of access the Teammate has to the specified Subuser. This property value may be either admin or restricted. When is property is set to restricted, the Teammate has only the permissions assigned in the scopes property.
The permissions or scopes that the Teammate can access on behalf of the Subuser. See Teammate Permissions for a complete list of available scopes.
Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.
