openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account SSO Settings 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 Settings
  description: Twilio SendGrid Single Sign-On Settings Operations
paths:
  /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.**


        The 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.**


        You 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.**


        You 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.**


        You 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'
components:
  responses:
    Sso401:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SsoErrorResponse'
    Sso500:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SsoErrorResponse'
    Sso403:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SsoErrorResponse'
    Sso400:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SsoErrorResponse'
    Sso429:
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SsoErrorResponse'
  schemas:
    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
    SsoErrorResponse:
      title: SSO Error Response
      type: array
      items:
        type: object
        properties:
          message:
            type: string
          field:
            nullable: true
            type: string
          error_id:
            type: string
    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
  requestBodies:
    PostPatchIntegration:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PostPatchIntegrationRequest'
  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.
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid