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

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

For more information about managing SSO Teammates, see the Twilio SendGrid SSO documentation.


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

scopes page anchor

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.

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.


Authorizationstringrequired
Default: Bearer <<YOUR_API_KEY_HERE>>
SchemaExample
emailstring<email>required

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.


first_namestringrequired

Set this property to the Teammate's first name.


last_namestringrequired

Set this property to the Teammate's last name.


is_adminboolean

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>

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]

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_accessboolean

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]

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.

201400401403429500
SchemaExample
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.

Create SSO Teammate

create-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 data = {
_25
"first_name": "Jane",
_25
"last_name": "Doe",
_25
"email": "jane_doe@example.com",
_25
"is_admin": true,
_25
"has_restricted_subuser_access": false
_25
};
_25
_25
const request = {
_25
url: `/v3/sso/teammates`,
_25
method: 'POST',
_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: