SendGrid SSO Teammates API

openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account SSO Teammates API
  summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts.
  description: 'The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.


    You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers) feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
  termsOfService: https://www.twilio.com/legal/tos
  contact:
    name: Twilio SendGrid Support
    url: https://support.sendgrid.com/hc/en-us
  license:
    name: MIT
    url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
  version: 1.0.0
  x-sendgrid:
    libraryPackage: account_provisioning
servers:
- url: https://api.sendgrid.com
  description: for global users and subusers
- url: https://api.eu.sendgrid.com
  description: for EU regional subusers
security:
- BearerAuth: []
tags:
- name: SSO Teammates
  description: Twilio SendGrid Single Sign-On Teammates Operations
paths:
  /v3/sso/teammates:
    post:
      operationId: CreateSsoTeammate
      summary: Create an SSO Teammate.
      tags:
      - SSO Teammates
      description: '**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**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions#persona-scopes) for a list of permsissions granted by persona. Lastly, you can assign individual permissions with the `scopes` property. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/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**](https://docs.sendgrid.com/ui/account-and-settings/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.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSsoTeammatesRequest'
            examples:
              Create Teammate with Subuser Access:
                value:
                  first_name: Jane
                  last_name: Doe
                  email: jane_doe@example.com
                  has_restricted_subuser_access: true
                  subuser_access:
                  - id: 12345
                    permission_type: admin
              Create Admin Teammate:
                value:
                  first_name: Jane
                  last_name: Doe
                  email: jane_doe@example.com
                  is_admin: true
                  has_restricted_subuser_access: false
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSsoTeammates201'
              examples:
                response:
                  value:
                    first_name: Jane
                    last_name: Doe
                    email: jane_doe@example.com
                    is_admin: true
                    is_sso: true
                    scopes:
                    - alerts.create
                    - alerts.read
                    - alerts.update
                    - alerts.delete
                    - asm.groups.create
                    - asm.groups.read
                    - asm.groups.update
                    - asm.groups.delete
                    - asm.groups.suppressions.create
                    - asm.groups.suppressions.read
                    - asm.groups.suppressions.update
                    - asm.groups.suppressions.delete
                    - asm.suppressions.global.create
                    - asm.suppressions.global.read
                    - asm.suppressions.global.update
                    - asm.suppressions.global.delete
                    - billing.create
                    - billing.read
                    - billing.update
                    - billing.delete
                    - ui.confirm_email
                    - signup.trigger_confirmation
                    - ui.provision
                    - ips.warmup.create
                    - ips.warmup.read
                    - ips.warmup.update
                    - ips.warmup.delete
                    - ips.pools.create
                    - ips.pools.read
                    - ips.pools.update
                    - ips.pools.delete
                    - ips.pools.ips.create
                    - ips.pools.ips.read
                    - ips.pools.ips.update
                    - ips.pools.ips.delete
                    - ips.assigned.read
                    - ips.create
                    - ips.read
                    - ips.update
                    - ips.delete
                    - mail.send
                    - mail_settings.read
                    - mail_settings.bcc.create
                    - mail_settings.bcc.read
                    - mail_settings.bcc.update
                    - mail_settings.bcc.delete
                    - mail_settings.address_whitelist.create
                    - mail_settings.address_whitelist.read
                    - mail_settings.address_whitelist.update
                    - mail_settings.address_whitelist.delete
                    - mail_settings.footer.create
                    - mail_settings.footer.read
                    - mail_settings.footer.update
                    - mail_settings.footer.delete
                    - mail_settings.forward_spam.create
                    - mail_settings.forward_spam.read
                    - mail_settings.forward_spam.update
                    - mail_settings.forward_spam.delete
                    - mail_settings.plain_content.create
                    - mail_settings.plain_content.read
                    - mail_settings.plain_content.update
                    - mail_settings.plain_content.delete
                    - mail_settings.spam_check.create
                    - mail_settings.spam_check.read
                    - mail_settings.spam_check.update
                    - mail_settings.spam_check.delete
                    - mail_settings.bounce_purge.create
                    - mail_settings.bounce_purge.read
                    - mail_settings.bounce_purge.update
                    - mail_settings.bounce_purge.delete
                    - mail_settings.forward_bounce.create
                    - mail_settings.forward_bounce.read
                    - mail_settings.forward_bounce.update
                    - mail_settings.forward_bounce.delete
                    - partner_settings.read
                    - partner_settings.new_relic.create
                    - partner_settings.new_relic.read
                    - partner_settings.new_relic.update
                    - partner_settings.new_relic.delete
                    - partner_settings.sendwithus.create
                    - partner_settings.sendwithus.read
                    - partner_settings.sendwithus.update
                    - partner_settings.sendwithus.delete
                    - tracking_settings.read
                    - tracking_settings.click.create
                    - tracking_settings.click.read
                    - tracking_settings.click.update
                    - tracking_settings.click.delete
                    - tracking_settings.subscription.create
                    - tracking_settings.subscription.read
                    - tracking_settings.subscription.update
                    - tracking_settings.subscription.delete
                    - tracking_settings.open.create
                    - tracking_settings.open.read
                    - tracking_settings.open.update
                    - tracking_settings.open.delete
                    - tracking_settings.google_analytics.create
                    - tracking_settings.google_analytics.read
                    - tracking_settings.google_analytics.update
                    - tracking_settings.google_analytics.delete
                    - user.webhooks.event.settings.create
                    - user.webhooks.event.settings.read
                    - user.webhooks.event.settings.update
                    - user.webhooks.event.settings.delete
                    - user.webhooks.event.test.create
                    - user.webhooks.event.test.read
                    - user.webhooks.event.test.update
                    - user.webhooks.event.test.delete
                    - user.webhooks.parse.settings.create
                    - user.webhooks.parse.settings.read
                    - user.webhooks.parse.settings.update
                    - user.webhooks.parse.settings.delete
                    - 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.create
                    - subusers.read
                    - subusers.update
                    - subusers.delete
                    - subusers.monitor.create
                    - subusers.monitor.read
                    - subusers.monitor.update
                    - subusers.monitor.delete
                    - subusers.credits.create
                    - subusers.credits.read
                    - subusers.credits.update
                    - subusers.credits.delete
                    - subusers.credits.remaining.create
                    - subusers.credits.remaining.read
                    - subusers.credits.remaining.update
                    - subusers.credits.remaining.delete
                    - subusers.reputations.read
                    - subusers.summary.read
                    - suppression.bounces.create
                    - suppression.bounces.read
                    - suppression.bounces.update
                    - suppression.bounces.delete
                    - suppression.blocks.create
                    - suppression.blocks.read
                    - suppression.blocks.update
                    - suppression.blocks.delete
                    - suppression.invalid_emails.create
                    - suppression.invalid_emails.read
                    - suppression.invalid_emails.update
                    - suppression.invalid_emails.delete
                    - suppression.spam_reports.create
                    - suppression.spam_reports.read
                    - suppression.spam_reports.update
                    - suppression.spam_reports.delete
                    - suppression.unsubscribes.create
                    - suppression.unsubscribes.read
                    - suppression.unsubscribes.update
                    - suppression.unsubscribes.delete
                    - templates.create
                    - templates.read
                    - templates.update
                    - templates.delete
                    - templates.versions.create
                    - templates.versions.read
                    - templates.versions.update
                    - templates.versions.delete
                    - templates.versions.activate.create
                    - templates.versions.activate.read
                    - templates.versions.activate.update
                    - templates.versions.activate.delete
                    - user.account.read
                    - user.credits.read
                    - user.email.create
                    - user.email.read
                    - user.email.update
                    - user.email.delete
                    - user.profile.create
                    - user.profile.read
                    - user.profile.update
                    - user.profile.delete
                    - user.password.create
                    - user.password.read
                    - user.password.update
                    - user.password.delete
                    - user.timezone.create
                    - user.timezone.read
                    - user.timezone.update
                    - user.timezone.delete
                    - user.username.create
                    - user.username.read
                    - user.username.update
                    - user.username.delete
                    - user.settings.enforced_tls.read
                    - user.settings.enforced_tls.update
                    - api_keys.create
                    - api_keys.read
                    - api_keys.update
                    - api_keys.delete
                    - credentials.create
                    - credentials.read
                    - credentials.update
                    - credentials.delete
                    - categories.create
                    - categories.read
                    - categories.update
                    - categories.delete
                    - mail_settings.template.create
                    - mail_settings.template.read
                    - mail_settings.template.update
                    - mail_settings.template.delete
                    - user.multifactor_authentication.create
                    - user.multifactor_authentication.read
                    - user.multifactor_authentication.update
                    - user.multifactor_authentication.delete
                    - newsletter.create
                    - newsletter.read
                    - newsletter.update
                    - newsletter.delete
                    - marketing_campaigns.create
                    - marketing_campaigns.read
                    - marketing_campaigns.update
                    - marketing_campaigns.delete
                    - ui.signup_complete
                    - mail.batch.create
                    - mail.batch.read
                    - mail.batch.update
                    - mail.batch.delete
                    - user.scheduled_sends.create
                    - user.scheduled_sends.read
                    - user.scheduled_sends.update
                    - user.scheduled_sends.delete
                    - access_settings.whitelist.create
                    - access_settings.whitelist.read
                    - access_settings.whitelist.update
                    - access_settings.whitelist.delete
                    - access_settings.activity.read
                    - whitelabel.create
                    - whitelabel.read
                    - whitelabel.update
                    - whitelabel.delete
                    - suppression.create
                    - suppression.read
                    - suppression.update
                    - suppression.delete
                    - teammates.create
                    - teammates.read
                    - teammates.update
                    - teammates.delete
                    - messages.read
                    - validations.email.read
                    - validations.email.create
                    - marketing.read
                    - marketing.automation.read
                    - design_library.read
                    - design_library.create
                    - design_library.update
                    - design_library.delete
                    - email_testing.read
                    - email_testing.write
                    - sender_verification_eligible
                    - sso.settings.create
                    - sso.settings.read
                    - sso.settings.update
                    - sso.settings.delete
                    - sender_verification_legacy
                    - sso.teammates.create
                    - sso.teammates.update
                    - 2fa_required
                    - di.bounce_block_classification.read
                    has_restricted_subuser_access: false
        '400':
          $ref: '#/components/responses/Sso400'
        '401':
          $ref: '#/components/responses/Sso401'
        '403':
          $ref: '#/components/responses/Sso403'
        '429':
          $ref: '#/components/responses/Sso429'
        '500':
          $ref: '#/components/responses/Sso500'
  /v3/sso/teammates/{username}:
    parameters:
    - name: username
      in: path
      description: Set this parameter to the Teammate's email address. This address must be the same address assigned to the Teammate in your IdP.
      required: true
      schema:
        type: string
        format: email
    patch:
      operationId: UpdateSsoTeammate
      summary: Edit an SSO Teammate
      tags:
      - SSO Teammates
      description: '**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


        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**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions#persona-scopes) for a list of permsissions granted by persona. Lastly, you can assign individual permissions with the `scopes` property. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/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**](https://docs.sendgrid.com/ui/account-and-settings/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.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchSsoTeammatesRequest'
            examples:
              Update Teammate with Subuser Access:
                value:
                  first_name: Jane
                  last_name: Doe
                  has_restricted_subuser_access: true
                  subuser_access:
                  - id: 12345
                    permission_type: admin
              Make Teammate an Admin:
                value:
                  first_name: Jane
                  last_name: Doe
                  is_admin: true
                  has_restricted_subuser_access: false
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatchSsoTeammates200'
              examples:
                response:
                  value:
                    address: 1234 Fake St.
                    address2: Suite 5
                    city: San Francisco
                    company: Example Dot Com, Inc.
                    country: United States
                    first_name: Jane
                    last_name: Doe
                    email: jane_doe@example.com
                    username: jane_doe@example.com
                    is_admin: true
                    is_sso: true
                    phone: '+15555555555'
                    state: CA
                    user_type: teammate
                    website: https://www.example.com
                    zip: '94105'
                    scopes:
                    - alerts.create
                    - alerts.read
                    - alerts.update
                    - alerts.delete
                    - asm.groups.create
                    - asm.groups.read
                    - asm.groups.update
                    - asm.groups.delete
                    - asm.groups.suppressions.create
                    - asm.groups.suppressions.read
                    - asm.groups.suppressions.update
                    - asm.groups.suppressions.delete
                    - asm.suppressions.global.create
                    - asm.suppressions.global.read
                    - asm.suppressions.global.update
                    - asm.suppressions.global.delete
                    - billing.create
                    - billing.read
                    - billing.update
                    - billing.delete
                    - ui.confirm_email
                    - signup.trigger_confirmation
                    - ui.provision
                    - ips.warmup.create
                    - ips.warmup.read
                    - ips.warmup.update
                    - ips.warmup.delete
                    - ips.pools.create
                    - ips.pools.read
                    - ips.pools.update
                    - ips.pools.delete
                    - ips.pools.ips.create
                    - ips.pools.ips.read
                    - ips.pools.ips.update
                    - ips.pools.ips.delete
                    - ips.assigned.read
                    - ips.create
                    - ips.read
                    - ips.update
                    - ips.delete
                    - mail.send
                    - mail_settings.read
                    - mail_settings.bcc.create
                    - mail_settings.bcc.read
                    - mail_settings.bcc.update
                    - mail_settings.bcc.delete
                    - mail_settings.address_whitelist.create
                    - mail_settings.address_whitelist.read
                    - mail_settings.address_whitelist.update
                    - mail_settings.address_whitelist.delete
                    - mail_settings.footer.create
                    - mail_settings.footer.read
                    - mail_settings.footer.update
                    - mail_settings.footer.delete
                    - mail_settings.forward_spam.create
                    - mail_settings.forward_spam.read
                    - mail_settings.forward_spam.update
                    - mail_settings.forward_spam.delete
                    - mail_settings.plain_content.create
                    - mail_settings.plain_content.read
                    - mail_settings.plain_content.update
                    - mail_settings.plain_content.delete
                    - mail_settings.spam_check.create
                    - mail_settings.spam_check.read
                    - mail_settings.spam_check.update
                    - mail_settings.spam_check.delete
                    - mail_settings.bounce_purge.create
                    - mail_settings.bounce_purge.read
                    - mail_settings.bounce_purge.update
                    - mail_settings.bounce_purge.delete
                    - mail_settings.forward_bounce.create
                    - mail_settings.forward_bounce.read
                    - mail_settings.forward_bounce.update
                    - mail_settings.forward_bounce.delete
                    - partner_settings.read
                    - partner_settings.new_relic.create
                    - partner_settings.new_relic.read
                    - partner_settings.new_relic.update
                    - partner_settings.new_relic.delete
                    - partner_settings.sendwithus.create
                    - partner_settings.sendwithus.read
                    - partner_settings.sendwithus.update
                    - partner_settings.sendwithus.delete
                    - tracking_settings.read
                    - tracking_settings.click.create
                    - tracking_settings.click.read
                    - tracking_settings.click.update
                    - tracking_settings.click.delete
                    - tracking_settings.subscription.create
                    - tracking_settings.subscription.read
                    - tracking_settings.subscription.update
                    - tracking_settings.subscription.delete
                    - tracking_settings.open.create
                    - tracking_settings.open.read
                    - tracking_settings.open.update
                    - tracking_settings.open.delete
                    - tracking_settings.google_analytics.create
                    - tracking_settings.google_analytics.read
                    - tracking_settings.google_analytics.update
                    - tracking_settings.google_analytics.delete
                    - user.webhooks.event.settings.create
                    - user.webhooks.event.settings.read
                    - user.webhooks.event.settings.update
                    - user.webhooks.event.settings.delete
                    - user.webhooks.event.test.create
                    - user.webhooks.event.test.read
                    - user.webhooks.event.test.update
                    - user.webhooks.event.test.delete
                    - user.webhooks.parse.settings.create
                    - user.webhooks.parse.settings.read
                    - user.webhooks.parse.settings.update
                    - user.webhooks.parse.settings.delete
                    - 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.create
                    - subusers.read
                    - subusers.update
                    - subusers.delete
                    - subusers.monitor.create
                    - subusers.monitor.read
                    - subusers.monitor.update
                    - subusers.monitor.delete
                    - subusers.credits.create
                    - subusers.credits.read
                    - subusers.credits.update
                    - subusers.credits.delete
                    - subusers.credits.remaining.create
                    - subusers.credits.remaining.read
                    - subusers.credits.remaining.update
                    - subusers.credits.remaining.delete
                    - subusers.reputations.read
                    - subusers.summary.read
                    - suppression.bounces.create
                    - suppression.bounces.read
                    - suppression.bounces.update
                    - suppression.bounces.delete
                    - suppression.blocks.create
                    - suppression.blocks.read
                    - suppression.blocks.update
                    - suppression.blocks.delete
                    - suppression.invalid_emails.create
                    - suppression.invalid_emails.read
                    - suppression.invalid_emails.update
                    - suppression.invalid_emails.delete
                    - suppression.spam_reports.create
                    - suppression.spam_reports.read
                    - suppression.spam_reports.update
                    - suppression.spam_reports.delete
                    - suppression.unsubscribes.create
                    - suppression.unsubscribes.read
                    - suppression.unsubscribes.update
                    - suppression.unsubscribes.delete
                    - templates.create
                    - templates.read
                    - templates.update
                    - templates.delete
                    - templates.versions.create
                    - templates.versions.read
                    - templates.versions.update
                    - templates.versions.delete
                    - templates.versions.activate.create
                    - templates.versions.activate.read
                    - templates.versions.activate.update
                    - templates.versions.activate.delete
                    - user.account.read
                    - user.credits.read
                    - user.email.create
                    - user.email.read
                    - user.email.update
                    - user.email.delete
                    - user.profile.create
                    - user.profile.read
                    - user.profile.update
                    - user.profile.delete
                    - user.password.create
                    - user.password.read
                    - user.password.update
                    - user.password.delete
                    - user.timezone.create
                    - user.timezone.read
                    - user.timezone.update
                    - user.timezone.delete
                    - user.username.create
                    - user.username.read
                    - user.username.update
                    - user.username.delete
                    - user.settings.enforced_tls.read
                    - user.settings.enforced_tls.update
                    - api_keys.create
                    - api_keys.read
                    - api_keys.update
                    - api_keys.delete
                    - credentials.create
                    - credentials.read
                    - credentials.update
                    - credentials.delete
                    - categories.create
                    - categories.read
                    - categories.update
                    - categories.delete
                    - mail_settings.template.create
                    - mail_settings.template.read
                    - mail_settings.template.update
                    - mail_settings.template.delete
                    - user.multifactor_authentication.create
                    - user.multifactor_authentication.read
                    - user.multifactor_authentication.update
                    - user.mu

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/sendgrid-sso-teammates-api-openapi.yml