{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Single Sign-On API", "summary": "The Single Sign-On API allows you to manage your SAML 2.0 SSO configurations.", "description": "The Single Sign-On API allows 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 application user interface](https://app.sendgrid.com/settings/sso).\n\nThe Single Sign-On Settings operations allow you to create, retrieve, modify, and delete SSO integrations for your Twilio SendGrid account. Each integration will correspond to a specific IdP such as Okta, Duo, or Microsoft Azure Active Directory.\n\nThe Single Sign-On Certificates operations allow you to create, modify, and delete SSO certificates. A SAML certificate allows your IdP and Twilio SendGrid to verify requests are coming from one another using the `public_certificate` and `integration_id` parameters.\n\nThe Single Sign-On Teammates operations allow 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 separate [Teammates API](https://docs.sendgrid.com/api-reference/teammates/).", "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": "sso" } }, "servers": [ { "url": "https://api.sendgrid.com", "description": "for global users and subusers" }, { "url": "https://api.eu.sendgrid.com", "description": "for EU regional subusers" } ], "paths": { "/v3/sso/certificates": { "post": { "operationId": "CreateSsoCertificate", "summary": "Create an SSO Certificate", "tags": [ "SSO Certificates" ], "description": "**This endpoint allows you to create an SSO certificate.**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "description": "", "properties": { "public_certificate": { "type": "string", "description": "This public certificate allows SendGrid to verify that SAML requests it receives are signed by an IdP that it recognizes." }, "enabled": { "type": "boolean", "description": "Indicates if the certificate is enabled." }, "integration_id": { "type": "string", "description": "An ID that matches a certificate to a specific IdP integration. This is the `id` returned by the \"Get All SSO Integrations\" endpoint." } }, "required": [ "public_certificate", "integration_id" ], "example": { "public_certificate": "", "enabled": false, "integration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoCertificateBody" }, "examples": { "response": { "value": { "public_certificate": "", "id": 66138975, "not_before": 1621289880, "not_after": 1621289880, "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } } } } } }, "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/certificates/{cert_id}": { "parameters": [ { "name": "cert_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "GetSsoCertificate", "summary": "Get an SSO Certificate", "tags": [ "SSO Certificates" ], "description": "**This endpoint allows you to retrieve an individual SSO certificate.**", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoCertificateBody" }, "examples": { "response": { "value": { "public_certificate": "", "id": 66138975, "not_before": 1621289880, "not_after": 1621289880, "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } } } } } }, "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" } } }, "patch": { "operationId": "UpdateSsoCertificate", "summary": "Update SSO Certificate", "tags": [ "SSO Certificates" ], "description": "**This endpoint allows you to update an existing certificate by ID.**\n\nYou can retrieve a certificate's ID from the response provided by the \"Get All SSO Integrations\" endpoint.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "public_certificate": { "type": "string", "description": "This public certificate allows SendGrid to verify that SAML requests it receives are signed by an IdP that it recognizes." }, "enabled": { "type": "boolean", "description": "Indicates whether or not the certificate is enabled." }, "integration_id": { "type": "string", "description": "An ID that matches a certificate to a specific IdP integration." } }, "example": { "public_certificate": "", "enabled": false, "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoCertificateBody" }, "examples": { "response": { "value": { "public_certificate": "", "id": 66138975, "not_before": 1621289880, "not_after": 1621289880, "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } } } } } }, "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" } } }, "delete": { "operationId": "DeleteSsoCertificate", "summary": "Delete an SSO Certificate", "tags": [ "SSO Certificates" ], "description": "**This endpoint allows you to delete an SSO certificate.**\n\nYou can retrieve a certificate's ID from the response provided by the \"Get All SSO Integrations\" endpoint.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoCertificateBody" }, "examples": { "response": { "value": { "public_certificate": "", "id": 66138975, "not_before": 1621289880, "not_after": 1621289880, "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } } } } } }, "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/integrations": { "post": { "operationId": "CreateSsoIntegration", "summary": "Create an SSO Integration", "tags": [ "SSO Settings" ], "description": "**This endpoint allows you to create an SSO integration.**", "requestBody": { "$ref": "#/components/requestBodies/PostPatchIntegration" }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoIntegration" }, "examples": { "response": { "value": { "name": "Twilio SendGrid", "enabled": true, "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", "entity_id": "http://www.okta.com/${org.externalKey}", "last_updated": 1621288964 } } } } } }, "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" } } }, "get": { "operationId": "ListSsoIntegration", "summary": "Get All SSO Integrations", "tags": [ "SSO Settings" ], "description": "**This endpoint allows you to retrieve all SSO integrations tied to your Twilio SendGrid account.**\n\nThe IDs returned by this endpoint can be used by the APIs additional endpoints to modify your SSO integrations.", "parameters": [ { "name": "si", "in": "query", "description": "If this parameter is set to `true`, the response will include the `completed_integration` field.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SsoIntegration" } }, "examples": { "response": { "value": [ { "name": "Twilio SendGrid", "enabled": true, "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", "entity_id": "http://www.okta.com/${org.externalKey}", "last_updated": 1621288520, "completed_integration": true, "id": "b0b98502-9408-4b24-9e3d-31ed7cb15312", "single_signon_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312", "audience_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312" } ] } } } } }, "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/integrations/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "GetSsoIntegration", "summary": "Get an SSO Integration", "tags": [ "SSO Settings" ], "description": "**This endpoint allows you to retrieve an SSO integration by ID.**\n\nYou can retrieve the IDs for your configurations from the response provided by the \"Get All SSO Integrations\" endpoint.", "parameters": [ { "name": "si", "in": "query", "description": "If this parameter is set to `true`, the response will include the `completed_integration` field.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoIntegration" }, "examples": { "response": { "value": { "name": "Twilio SendGrid", "enabled": true, "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", "entity_id": "http://www.okta.com/${org.externalKey}", "last_updated": 1621288964, "completed_integration": true, "id": "b0b98502-9408-4b24-9e3d-31ed7cb15312", "audience_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312" } } } } } }, "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" } } }, "patch": { "operationId": "UpdateSsoIntegration", "summary": "Update an SSO Integration", "tags": [ "SSO Settings" ], "description": "**This endpoint allows you to modify an exisiting SSO integration.**\n\nYou can retrieve the IDs for your configurations from the response provided by the \"Get All SSO Integrations\" endpoint.", "parameters": [ { "name": "si", "in": "query", "description": "If this parameter is set to `true`, the response will include the `completed_integration` field.", "schema": { "type": "boolean" } } ], "requestBody": { "$ref": "#/components/requestBodies/PostPatchIntegration" }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoIntegration" }, "examples": { "response": { "value": { "name": "Twilio SendGrid", "enabled": true, "signin_url": "https://example.okta.com/home/examplecompany/yokpGWsmpRUcuvXFb4x6/nfaVADNhuHvvReAEV4x6", "signout_url": "https://example.okta.com/login/signout?fromURI=exampleappurl", "entity_id": "http://www.okta.com/${org.externalKey}", "last_updated": 1621288964, "id": "b0b98502-9408-4b24-9e3d-31ed7cb15312", "single_signon_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312", "audience_url": "https://api.sendgrid.com/v3/public/sso/saml/response/id/b0b98502-9408-4b24-9e3d-31ed7cb15312" } } } } } }, "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" } } }, "delete": { "operationId": "DeleteSsoIntegration", "summary": "Delete an SSO Integration", "tags": [ "SSO Settings" ], "description": "**This endpoint allows you to delete an IdP configuration by ID.**\n\nYou can retrieve the IDs for your configurations from the response provided by the \"Get All SSO Integrations\" endpoint.", "responses": { "204": { "description": "" }, "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/integrations/{integration_id}/certificates": { "parameters": [ { "name": "integration_id", "in": "path", "description": "An ID that matches a certificate to a specific IdP integration.", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "ListSsoIntegrationCertificate", "summary": "Get All SSO Certificates by Integration", "tags": [ "SSO Certificates" ], "description": "**This endpoint allows you to retrieve all your IdP configurations by configuration ID.**\n\nThe `integration_id` expected by this endpoint is the `id` returned in the response by the \"Get All SSO Integrations\" endpoint.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SsoCertificateBody" } }, "examples": { "response": { "value": [ { "public_certificate": "", "id": 66138975, "not_before": 1621289880, "not_after": 1621289880, "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } ] } } } } }, "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": { "post": { "operationId": "CreateSsoTeammate", "summary": "Create an SSO Teammate.", "tags": [ "SSO Teammates" ], "description": "**This endpoint allows you to create an SSO Teammate.**\n\nThe email address provided for the Teammate will also function as the Teammate's username. Once created, the Teammate's email address cannot be changed.\n\n### Scopes\n\nWhen 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`.\n\nYou 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.\n\n### Subuser access\n\nSendGrid 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.\n\nWhen 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.**\n\nOnly the parent user and Teammates with admin permissions can update another Teammate's permissions.\n\n### Scopes\n\nWhen 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`.\n\nYou 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.\n\n### Subuser access\n\nSendGrid 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.\n\nWhen 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.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" } } } } }, "components": { "schemas": { "SsoCertificateBody": { "title": "Single Sign-On Certificate Body", "type": "object", "properties": { "public_certificate": { "type": "string", "description": "This certificate is used by Twilio SendGrid to verify that SAML requests are coming from Okta. This is called the X509 certificate in the Twilio SendGrid UI." }, "id": { "type": "number", "description": "A unique ID assigned to the certificate by SendGrid." }, "not_before": { "type": "number", "description": "A unix timestamp (e.g., 1603915954) that indicates the time before which the certificate is not valid." }, "not_after": { "type": "number", "description": "A unix timestamp (e.g., 1603915954) that indicates the time after which the certificate is no longer valid." }, "intergration_id": { "type": "string", "description": "An ID that matches a certificate to a specific IdP integration." } }, "example": { "public_certificate": "", "id": 66138975, "not_before": 1621289880, "not_after": 1621289880, "intergration_id": "b0b98502-9408-4b24-9e3d-31ed7cb15312" } }, "SsoIntegration": { "title": "Single Sign-On Integration", "type": "object", "properties": { "name": { "type": "string", "description": "The name of your integration. This name can be anything that makes sense for your organization (eg. Twilio SendGrid)" }, "enabled": { "type": "boolean", "description": "Indicates if the integration is enabled." }, "signin_url": { "type": "string", "description": "The IdP's SAML POST endpoint. This endpoint should receive requests and initiate an SSO login flow. This is called the \"Embed Link\" in the Twilio SendGrid UI." }, "signout_url": { "type": "string", "description": "This URL is relevant only for an IdP-initiated authentication flow. If a user authenticates from their IdP, this URL will return them to their IdP when logging out." }, "entity_id": { "type": "string", "description": "An identifier provided by your IdP to identify Twilio SendGrid in the SAML interaction. This is called the \"SAML Issuer ID\" in the Twilio SendGrid UI." }, "completed_integration": { "type": "boolean", "description": "Indicates if the integration is complete." }, "last_updated": { "type": "number", "description": "A timestamp representing the last time the configuration was modified." }, "id": { "type": "string", "description": "A unique ID assigned to the configuration by SendGrid." }, "single_signon_url": { "type": "string", "description": "The URL where your IdP should POST its SAML response. This is the Twilio SendGrid URL that is responsible for receiving and parsing a SAML assertion. This is the same URL as the Audience URL when using SendGrid." }, "audience_url": { "type": "string", "description": "The URL where your IdP should POST its SAML response. This is the Twilio SendGrid URL that is responsible for receiving and parsing a SAML assertion. This is the same URL as the Single Sign-On URL when using SendGrid." } }, "required": [ "enabled", "entity_id", "last_updated", "name", "signin_url", "signout_url" ] }, "PostPatchIntegrationRequest": { "title": "Create Integration Request", "type": "object", "properties": { "name": { "type": "string", "description": "The name of your integration. This name can be anything that makes sense for your organization (eg. Twilio SendGrid)" }, "enabled": { "type": "boolean", "description": "Indicates if the integration is enabled." }, "signin_url": { "type": "string", "description": "The IdP's SAML POST endpoint. This endpoint should receive requests and initiate an SSO login flow. This is called the \"Embed Link\" in the Twilio SendGrid UI." }, "signout_url": { "type": "string", "description": "This URL is relevant only for an IdP-initiated authentication flow. If a user authenticates from their IdP, this URL will return them to their IdP when logging out." }, "entity_id": { "type": "string", "description": "An identifier provided by your IdP to identify Twilio SendGrid in the SAML interaction. This is called the \"SAML Issuer ID\" in the Twilio SendGrid UI." }, "completed_integration": { "type": "boolean", "description": "Indicates if the integration is complete." } }, "required": [ "name", "enabled", "signin_url", "signout_url", "entity_id" ] }, "SsoTeammatesBaseRequestProps": { "type": "object", "properties": { "first_name": { "type": "string", "description": "Set this property to the Teammate's first name." }, "last_name": { "type": "string", "description": "Set this property to the Teammate's last name." }, "is_admin": { "type": "boolean", "description": "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`\u2014an admin will be allocated all scopes. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions) for a complete list of scopes." }, "persona": { "type": "string", "description": "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**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions) for a full list of the scopes assigned to each persona.", "$ref": "#/components/schemas/Persona" }, "scopes": { "type": "array", "description": "Add or remove permissions from a Teammate using this `scopes` property. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/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`\u2014assigning a `persona` or setting `is_admin` to `true` will allocate a group of permissions to the Teammate.", "items": { "type": "string" } }, "has_restricted_subuser_access": { "type": "boolean", "description": "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`\u2014a Teammate cannot specify scopes for the parent account and have restricted Subuser access." }, "subuser_access": { "type": "array", "description": "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`.", "items": { "type": "object", "description": "An array of Subusers to which the Teammate should have access.", "properties": { "id": { "type": "integer", "description": "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](https://docs.sendgrid.com/api-reference/subusers-api/)." }, "permission_type": { "type": "string", "description": "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.", "$ref": "#/components/schemas/PermissionType" }, "scopes": { "type": "array", "description": "Add or remove permissions that the Teammate can access on behalf of the Subuser. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/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`\u2014administrators have full access to the specified Subuser.", "items": { "type": "string" } } }, "required": [ "id", "permission_type" ] } } }, "required": [ "first_name", "last_name" ] }, "PostSsoTeammatesRequest": { "title": "Single Sign-On Teammate Create Request Body", "summary": "The request body accepted by the POST endpoint that creates a new webhook.", "example": { "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" ] } ] }, "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "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_name": { "type": "string", "description": "Set this property to the Teammate's first name." }, "last_name": { "type": "string", "description": "Set this property to the Teammate's last name." }, "is_admin": { "type": "boolean", "description": "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`\u2014an admin will be allocated all scopes. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions) for a complete list of scopes." }, "persona": { "type": "string", "description": "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**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions) for a full list of the scopes assigned to each persona.", "$ref": "#/components/schemas/Persona" }, "scopes": { "type": "array", "description": "Add or remove permissions from a Teammate using this `scopes` property. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/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`\u2014assigning a `persona` or setting `is_admin` to `true` will allocate a group of permissions to the Teammate.", "items": { "type": "string" } }, "has_restricted_subuser_access": { "type": "boolean", "description": "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`\u2014a Teammate cannot specify scopes for the parent account and have restricted Subuser access." }, "subuser_access": { "type": "array", "description": "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`.", "items": { "type": "object", "description": "An array of Subusers to which the Teammate should have access.", "properties": { "id": { "type": "integer", "description": "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](https://docs.sendgrid.com/api-reference/subusers-api/)." }, "permission_type": { "type": "string", "description": "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.", "$ref": "#/components/schemas/PermissionType" }, "scopes": { "type": "array", "description": "Add or remove permissions that the Teammate can access on behalf of the Subuser. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/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`\u2014administrators have full access to the specified Subuser.", "items": { "type": "string" } } }, "required": [ "id", "permission_type" ] } } }, "required": [ "email", "first_name", "last_name" ] }, "PatchSsoTeammatesRequest": { "title": "Single Sign-On Teammate Update Request Body", "summary": "Single Sign-on Teammate Request Body for update, PATCH, Teammate operations.", "$ref": "#/components/schemas/SsoTeammatesBaseRequestProps" }, "SsoTeammatesBaseResponseProps": { "type": "object", "properties": { "first_name": { "type": "string", "description": "The Teammate's first name." }, "last_name": { "type": "string", "description": "The Teammate's last name." }, "email": { "type": "string", "format": "email", "description": "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_admin": { "type": "boolean", "description": "Indicates if the Teammate has administrator permissions. When set to `true`, the Teammate is an admin." }, "is_sso": { "type": "boolean", "description": "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." }, "scopes": { "type": "array", "description": "The permissions or scopes currently assigned to the Teammate. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions) for a complete list of available scopes.", "items": { "type": "string" } } } }, "SsoTeammatesRestrictedSubuserResponseProps": { "type": "object", "properties": { "has_restricted_subuser_access": { "type": "boolean", "description": "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_access": { "type": "array", "description": "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`.", "items": { "type": "object", "description": "An array of Subusers to which the Teammate has access.", "properties": { "id": { "type": "integer", "description": "The ID of a Subuser to which the Teammate has access. You can retrieve Subuser IDs from the [Subusers API](https://docs.sendgrid.com/api-reference/subusers-api/)." }, "username": { "type": "string", "description": "The username of a Subuser to which the Teammate has access." }, "email": { "type": "string", "description": "The email address of a Subuser to which the Teammate has access." }, "disabled": { "type": "boolean", "description": "Indicates if the Subuser is active for the SendGrid account." }, "permission_type": { "type": "string", "description": "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.", "$ref": "#/components/schemas/PermissionType1" }, "scopes": { "type": "array", "description": "The permissions or scopes that the Teammate can access on behalf of the Subuser. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions) for a complete list of available scopes.", "items": { "type": "string" } } } } } } }, "PostSsoTeammates201": { "title": "Single Sign-On Teammates POST Response.", "description": "Successful SSO Teammates POST Response.", "type": "object", "properties": { "first_name": { "type": "string", "description": "The Teammate's first name." }, "last_name": { "type": "string", "description": "The Teammate's last name." }, "email": { "type": "string", "format": "email", "description": "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_admin": { "type": "boolean", "description": "Indicates if the Teammate has administrator permissions. When set to `true`, the Teammate is an admin." }, "is_sso": { "type": "boolean", "description": "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." }, "scopes": { "type": "array", "description": "The permissions or scopes currently assigned to the Teammate. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions) for a complete list of available scopes.", "items": { "type": "string" } }, "has_restricted_subuser_access": { "type": "boolean", "description": "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_access": { "type": "array", "description": "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`.", "items": { "type": "object", "description": "An array of Subusers to which the Teammate has access.", "properties": { "id": { "type": "integer", "description": "The ID of a Subuser to which the Teammate has access. You can retrieve Subuser IDs from the [Subusers API](https://docs.sendgrid.com/api-reference/subusers-api/)." }, "username": { "type": "string", "description": "The username of a Subuser to which the Teammate has access." }, "email": { "type": "string", "description": "The email address of a Subuser to which the Teammate has access." }, "disabled": { "type": "boolean", "description": "Indicates if the Subuser is active for the SendGrid account." }, "permission_type": { "type": "string", "description": "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.", "$ref": "#/components/schemas/PermissionType1" }, "scopes": { "type": "array", "description": "The permissions or scopes that the Teammate can access on behalf of the Subuser. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions) for a complete list of available scopes.", "items": { "type": "string" } } } } } } }, "PatchSsoTeammates200": { "title": "Single Sign-On Teammates PATCH Response.", "description": "Successful SSO Teammates PATCH response.", "type": "object", "properties": { "address": { "type": "string", "description": "The Teammate's street address." }, "address2": { "type": "string", "description": "The Teammate's apartment number, suite number, or other secondary address information that is not part of the physical street address." }, "city": { "type": "string", "description": "The Teammate's city." }, "company": { "type": "string", "description": "The Teammate's company name." }, "country": { "type": "string", "description": "The Teammate's country of residence." }, "username": { "type": "string", "description": "The Teammate's username. This property is set to the Teammate's email address." }, "phone": { "type": "string", "description": "The Teammate's phone number." }, "state": { "type": "string", "description": "The Teammate's state or province." }, "user_type": { "type": "string", "description": "A Teammate can be an `admin`, `owner`, or `teammate`. Each role is associated with the scope of the Teammate's permissions.", "$ref": "#/components/schemas/UserType" }, "website": { "type": "string", "description": "A website associated with the Teammate." }, "zip": { "type": "string", "description": "The Teammate's zip code." }, "first_name": { "type": "string", "description": "The Teammate's first name." }, "last_name": { "type": "string", "description": "The Teammate's last name." }, "email": { "type": "string", "format": "email", "description": "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_admin": { "type": "boolean", "description": "Indicates if the Teammate has administrator permissions. When set to `true`, the Teammate is an admin." }, "is_sso": { "type": "boolean", "description": "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." }, "scopes": { "type": "array", "description": "The permissions or scopes currently assigned to the Teammate. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions) for a complete list of available scopes.", "items": { "type": "string" } }, "has_restricted_subuser_access": { "type": "boolean", "description": "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_access": { "type": "array", "description": "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`.", "items": { "type": "object", "description": "An array of Subusers to which the Teammate has access.", "properties": { "id": { "type": "integer", "description": "The ID of a Subuser to which the Teammate has access. You can retrieve Subuser IDs from the [Subusers API](https://docs.sendgrid.com/api-reference/subusers-api/)." }, "username": { "type": "string", "description": "The username of a Subuser to which the Teammate has access." }, "email": { "type": "string", "description": "The email address of a Subuser to which the Teammate has access." }, "disabled": { "type": "boolean", "description": "Indicates if the Subuser is active for the SendGrid account." }, "permission_type": { "type": "string", "description": "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.", "$ref": "#/components/schemas/PermissionType1" }, "scopes": { "type": "array", "description": "The permissions or scopes that the Teammate can access on behalf of the Subuser. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions) for a complete list of available scopes.", "items": { "type": "string" } } } } } } }, "SsoErrorResponse": { "title": "SSO Error Response", "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "nullable": true, "type": "string" }, "error_id": { "type": "string" } } } }, "Persona": { "type": "string", "enum": [ "accountant", "developer", "marketer", "observer" ] }, "PermissionType": { "type": "string", "enum": [ "admin", "restricted" ] }, "PermissionType1": { "type": "string", "enum": [ "admin", "restricted" ] }, "UserType": { "type": "string", "enum": [ "admin", "owner", "teammate" ] } }, "responses": { "Sso400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoErrorResponse" } } } }, "Sso401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoErrorResponse" } } } }, "Sso403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoErrorResponse" } } } }, "Sso429": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoErrorResponse" } } } }, "Sso500": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SsoErrorResponse" } } } } }, "parameters": {}, "examples": {}, "requestBodies": { "PostPatchIntegration": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostPatchIntegrationRequest" } } } } }, "headers": {}, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Twilio SendGrid requires you to authenticate with its APIs using an API key. The API key must be sent as a bearer token in the Authorization header." } } }, "tags": [ { "name": "SSO Certificates", "description": "Twilio SendGrid Single Sign-On Certificate Operations" }, { "name": "SSO Settings", "description": "Twilio SendGrid Single Sign-On Settings Operations" }, { "name": "SSO Teammates", "description": "Twilio SendGrid Single Sign-On Teammates Operations" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }