Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Edit an SSO Teammate



API Overview

api-overview page anchor

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(link takes you to an external page).

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.


PATCH/v3/sso/teammates/{username}

Base url: https://api.sendgrid.com

This endpoint allows you to modify an existing SSO Teammate.

Only the parent user and Teammates with admin permissions can update another Teammate's permissions.

Scopes

scopes page anchor

When updating 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.

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.


Property nameTypeRequiredDescription
Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>
Property nameTypeRequiredDescription
usernamestring<email>required

Set this parameter to the Teammate's email address. This address must be the same address assigned to the Teammate in your IdP.

SchemaExample
Property nameTypeRequiredDescriptionChild properties
first_namestringrequired

Set this property to the Teammate's first name.


last_namestringrequired

Set this property to the Teammate's last name.


is_adminbooleanOptional

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.


personaenum<string>Optional

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.

Possible values:
accountantdevelopermarketerobserver

scopesarray[string]Optional

Add 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.


has_restricted_subuser_accessbooleanOptional

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.


subuser_accessarray[object]Optional

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.

200400401403429500
SchemaExample
Property nameTypeRequiredDescriptionChild properties
addressstring

The Teammate's street address.


address2string

The Teammate's apartment number, suite number, or other secondary address information that is not part of the physical street address.


citystring

The Teammate's city.


companystring

The Teammate's company name.


countrystring

The Teammate's country of residence.


usernamestring

The Teammate's username. This property is set to the Teammate's email address.


phonestring

The Teammate's phone number.


statestring

The Teammate's state or province.


user_typeenum<string>

A Teammate can be an admin, owner, or teammate. Each role is associated with the scope of the Teammate's permissions.

Possible values:
adminownerteammate

websitestring

A website associated with the Teammate.


zipstring

The Teammate's zip code.


first_namestring

The Teammate's first name.


last_namestring

The Teammate's last name.


emailstring<email>

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.


is_adminboolean

Indicates if the Teammate has administrator permissions. When set to true, the Teammate is an admin.


is_ssoboolean

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.


scopesarray[string]

The permissions or scopes currently assigned to the Teammate. See Teammate Permissions for a complete list of available scopes.


has_restricted_subuser_accessboolean

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.


subuser_accessarray[object]

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.

Edit an SSO Teammate

edit-an-sso-teammate page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
curl

_25
const client = require('@sendgrid/client');
_25
client.setApiKey(process.env.SENDGRID_API_KEY);
_25
_25
const username = "brian12@example.net";
_25
const data = {
_25
"first_name": "Jane",
_25
"last_name": "Doe",
_25
"is_admin": true,
_25
"has_restricted_subuser_access": false
_25
};
_25
_25
const request = {
_25
url: `/v3/sso/teammates/${username}`,
_25
method: 'PATCH',
_25
body: data
_25
}
_25
_25
client.request(request)
_25
.then(([response, body]) => {
_25
console.log(response.statusCode);
_25
console.log(response.body);
_25
})
_25
.catch(error => {
_25
console.error(error);
_25
});


Rate this page: