# Create an SSO Integration The Single Sign-On APIs allow you to manage your SAML 2.0 SSO configurations. You can also work with your SSO integrations using the [SSO section of the Twilio SendGrid App](https://app.sendgrid.com/settings/sso). The Single Sign-On Settings API allows 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. ## Operation overview ```json {"path":"https://api.sendgrid.com/v3/sso/integrations","method":"post","servers":[{"url":"https://api.sendgrid.com","description":"for global users and subusers"},{"url":"https://api.eu.sendgrid.com","description":"for EU regional subusers"}]} ``` **This endpoint allows you to create an SSO integration.** ## Operation details ### Authentication API Key ### Headers ```json [{"in":"header","name":"Authorization","required":true,"default":"Bearer <>","schema":{"type":"string"}}] ``` ### Request body ```json {"schema":{"title":"Create Integration Request","type":"object","required":["name","enabled","signin_url","signout_url","entity_id"],"refName":"PostPatchIntegrationRequest","modelName":"PostPatchIntegrationRequest","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."}}},"encodingType":"application/json"} ``` ### Responses ```json [{"responseCode":"200","schema":{"description":"","content":{"application/json":{"schema":{"title":"Single Sign-On Integration","type":"object","required":["enabled","entity_id","last_updated","name","signin_url","signout_url"],"refName":"SsoIntegration","modelName":"SsoIntegration","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."}}},"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}}}}}}},{"responseCode":"400","schema":{"description":"","content":{"application/json":{"schema":{"title":"SSO Error Response","type":"array","refName":"SsoErrorResponse","modelName":"SsoErrorResponse","items":{"type":"object","properties":{"message":{"type":"string"},"field":{"nullable":true,"type":"string"},"error_id":{"type":"string"}}}}}},"refName":"#/components/responses/Sso400","modelName":"__components_responses_Sso400"}},{"responseCode":"401","schema":{"description":"","content":{"application/json":{"schema":{"title":"SSO Error Response","type":"array","refName":"SsoErrorResponse","modelName":"SsoErrorResponse","items":{"type":"object","properties":{"message":{"type":"string"},"field":{"nullable":true,"type":"string"},"error_id":{"type":"string"}}}}}},"refName":"#/components/responses/Sso401","modelName":"__components_responses_Sso401"}},{"responseCode":"403","schema":{"description":"","content":{"application/json":{"schema":{"title":"SSO Error Response","type":"array","refName":"SsoErrorResponse","modelName":"SsoErrorResponse","items":{"type":"object","properties":{"message":{"type":"string"},"field":{"nullable":true,"type":"string"},"error_id":{"type":"string"}}}}}},"refName":"#/components/responses/Sso403","modelName":"__components_responses_Sso403"}},{"responseCode":"429","schema":{"description":"","content":{"application/json":{"schema":{"title":"SSO Error Response","type":"array","refName":"SsoErrorResponse","modelName":"SsoErrorResponse","items":{"type":"object","properties":{"message":{"type":"string"},"field":{"nullable":true,"type":"string"},"error_id":{"type":"string"}}}}}},"refName":"#/components/responses/Sso429","modelName":"__components_responses_Sso429"}},{"responseCode":"500","schema":{"description":"","content":{"application/json":{"schema":{"title":"SSO Error Response","type":"array","refName":"SsoErrorResponse","modelName":"SsoErrorResponse","items":{"type":"object","properties":{"message":{"type":"string"},"field":{"nullable":true,"type":"string"},"error_id":{"type":"string"}}}}}},"refName":"#/components/responses/Sso500","modelName":"__components_responses_Sso500"}}] ``` Create an SSO Integration ```js const client = require("@sendgrid/client"); client.setApiKey(process.env.SENDGRID_API_KEY); const data = { name: "Miss Christine Morgan", enabled: false, signin_url: "https://www.example.com", signout_url: "https://www.example.com", entity_id: "entity_id", }; const request = { url: `/v3/sso/integrations`, method: "POST", body: data, }; client .request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) .catch((error) => { console.error(error); }); ``` ```python import os from sendgrid import SendGridAPIClient sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY")) data = { "name": "Miss Christine Morgan", "enabled": False, "signin_url": "https://www.example.com", "signout_url": "https://www.example.com", "entity_id": "entity_id", } response = sg.client.sso.integrations.post(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using SendGrid; public class Program { public static async Task Main() { string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY"); var client = new SendGridClient(apiKey); var data = @"{ ""name"": ""Miss Christine Morgan"", ""enabled"": false, ""signin_url"": ""https://www.example.com"", ""signout_url"": ""https://www.example.com"", ""entity_id"": ""entity_id"" }"; var response = await client.RequestAsync( method: SendGridClient.Method.POST, urlPath: "sso/integrations", requestBody: data); Console.WriteLine(response.StatusCode); Console.WriteLine(response.Body.ReadAsStringAsync().Result); Console.WriteLine(response.Headers.ToString()); } } ``` ```java import com.sendgrid.*; import java.io.IOException; import org.json.JSONObject; import java.util.HashMap; public class Example { public static void main(String[] args) throws IOException { try { SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY")); Request request = new Request(); request.setMethod(Method.POST); request.setEndpoint("/sso/integrations"); request.setBody(new JSONObject(new HashMap() { { put("name", "Miss Christine Morgan"); put("enabled", false); put("signin_url", "https://www.example.com"); put("signout_url", "https://www.example.com"); put("entity_id", "entity_id"); } }).toString()); Response response = sg.api(request); System.out.println(response.getStatusCode()); System.out.println(response.getBody()); System.out.println(response.getHeaders()); } catch (IOException ex) { throw ex; } } } ``` ```go package main import ( "fmt" "github.com/sendgrid/sendgrid-go" "os" ) func main() { apiKey := os.Getenv("SENDGRID_API_KEY") host := "https://api.sendgrid.com" request := sendgrid.GetRequest(apiKey, "/v3/sso/integrations", host) request.Method = "POST" request.Body = []byte(`{ "name": "Miss Christine Morgan", "enabled": false, "signin_url": "https://www.example.com", "signout_url": "https://www.example.com", "entity_id": "entity_id" }`) response, err := sendgrid.API(request) if err != nil { fmt.Println(err.Error()) os.Exit(1) } else { fmt.Println(response.StatusCode) fmt.Println(response.Body) fmt.Println(response.Headers) } } ``` ```php /sendgrid-php.php'; $apiKey = getenv("SENDGRID_API_KEY"); $sg = new \SendGrid($apiKey); $request_body = json_decode('{ "name": "Miss Christine Morgan", "enabled": false, "signin_url": "https://www.example.com", "signout_url": "https://www.example.com", "entity_id": "entity_id" }'); try { $response = $sg->client ->sso() ->integrations() ->post($request_body); print $response->statusCode() . "\n"; print_r($response->headers()); print $response->body() . "\n"; } catch (Exception $ex) { echo "Caught exception: " . $ex->getMessage(); } ``` ```ruby require 'sendgrid-ruby' include SendGrid sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']) data = JSON.parse('{ "name": "Miss Christine Morgan", "enabled": false, "signin_url": "https://www.example.com", "signout_url": "https://www.example.com", "entity_id": "entity_id" }') response = sg.client.sso.integrations.post(request_body: data) puts response.status_code puts response.headers puts response.body ``` ```bash curl -X POST "https://api.sendgrid.com/v3/sso/integrations" \ --header "Authorization: Bearer $SENDGRID_API_KEY" \ --header "Content-Type: application/json" \ --data '{"name": "Miss Christine Morgan", "enabled": false, "signin_url": "https://www.example.com", "signout_url": "https://www.example.com", "entity_id": "entity_id"}' ```