Account Provisioning API Overview

The Account Provisioning API uses standard Twilio Sendgrid API Keys for authentication and authorization. Once onboarded as a reseller, any API keys you create will have access to the Account Provisioning API. Twilio SendGrid recommends creating an Admin API key to manage your Account Provisioning API account. An Admin key is also known as a Full Access key in the Twilio SendGrid user interface.

If you are new to Twilio SendGrid API keys, see the API key docs to create an API key. The Twilio SendGrid v3 APIs expect the key to be passed as a Bearer Token in an Authorization header. See How to Use the SendGrid v3 API for instructions.

The following documentation refers to the owner of an Account Provisioning API account as the reseller. The accounts a reseller owns and manages through this API are referred to as customer accounts. The operations available are provided to you, the reseller, in order to manage your customer accounts.

The Twilio SendGrid Account Provisioning API allows you to create and manage your customers' accounts. This page provides an overview of the most common operations a reseller will perform:

• Creating a customer account.
• Understanding account state.
• Managing customer account offerings.
• Deactivating and removing account resources.
• Authenticating customers with single sign-on (SSO).

For information about the other Account Provisioning API operations available, see the API reference documentation for each operation.

Creating a new customer account is done with a single POST operation that will return the unique Twilio SendGrid account ID for the newly created account. The Create Account operation requires a JSON request body containing a profile object and an array of offerings objects.

The profile object contains a customer's identity information such as their first_name, last_name, and email. The fields in the profile object are optional — the customer will be prompted at their first login to enter any profile information you choose not to include when creating the account. See the API reference for all profile fields.

The offerings array contains offering objects that list the offering's name, type, and quantity. The offerings array is required, and it defines the Twilio SendGrid features or offerings available to the customer's account. The offerings available will depend on your agreement with Twilio SendGrid.

To retrieve a list of all the offerings that you can assign to a customer account, use the List Offerings endpoint. Because the available offerings will change infrequently, you may wish to cache the List Offerings response rather than call the endpoint before each account creation or update. A new account may start on any email offering at any price point. Upgrades and downgrades are also available immediately after account provisioning.

The following JSON block shows a common request body used to create a new customer account.

1
{
2
  "profile": {
3
      "first_name": "Jane",
4
      "last_name": "Doe",
5
      "company_name": "Cake or Pie Bakery",
6
      "company_website": "www.example.com",
7
      "email": "jdoe@example.com",
8
      "phone": "+15555555555",
9
      "timezone": "Asia/Tokyo"
10
  },
11
  "offerings": [
12
      {
13
          "name": "milne.ei.pro-100k.v1",
14
          "type": "package",
15
          "quantity": 1
16
      }
17
    ]
18
}

The response to a new account creation is the Twilio Sendgrid account ID. This account ID is used in all subsequent calls to the Account Provisioning API, so you should record it in your database for future use.

1
{
2
  "account_id": "sg2a2bcd3ef4ab5c67d8efab91c01de2fa"
3
}

To create a new customer test account with Account Provisioning API, you must pass in a custom header as follows:

T-Test-Account: true

A test account will not be allocated a dedicated IP and will be limited to sending 100 email per day irrespective of the offerings used to create the account. An account not created as a test account using this custom header cannot be updated to be a test account.

A customer account can be in one of five states, activated, deactivated, suspended, banned, or indeterminate*. Setting the customer account state is done with a single PUT operation using one of these states. Retrieving the customer account state is done with a single GET operation that will return the state for the account. The following table shows the actions available to an account based on its state.

Table of account states and immediately affected actions

* If you find an account in the indeterminate state, please contact Twilio SendGrid support for assistance.

Once a customer account is created, the most common need is to upgrade or downgrade the account to a different email package, otherwise known as an "offering." In addition to common email infrastructure offerings, your partner organization may have "add-on" offerings available including features such as Marketing Campaigns, Dedicated IP Addresses, and Expert Services.

Changing an account's offerings is done with a single PUT operation requiring a JSON request body that contains an offerings array of offering objects.

Because the update operation is a PUT request, you can remove offerings by omitting them from the update request. This means you must also pass the endpoint any offerings you want the account to retain — each operation overwrites the existing offerings for the account entirely. To retrieve a list of all the offerings you may assign to a customer account, use the List Offerings endpoint. To see a list of the offerings currently assigned to an individual customer account, use the Get Account Offerings endpoint.

The response to a change offering request is the account's resulting offerings list, which is identical to what will be returned on subsequent calls to the Get Account Offerings endpoint.

You can deactivate a customer account using the Update Account State operation to set the account state to deactivated.

1
{
2
    "state": "deactivated"
3
}

You can remove features such as Subusers and Dedicated IP addresses from a customer account using the Update Account Offerings operation. Update the account with a free offerings payload.

Once a customer account is created, the reseller can trigger a login to the Twilio Sendgrid UI for the customer with no password needed.

Expand image

In addition to providing a seamless customer experience for accessing the Twilio Sendgrid UI, our Account Provisioning SSO also removes the need for a Sendgrid-based username and password. The reseller can manage their customers' authentication credentials without sharing any of that information with Twilio SendGrid.

The redirect generated as part of this flow contains a one-time authorization code used to log the user into the Twilio SendGrid UI. This one-time code is good 60 seconds and can be used for login once, ensuring that any type of man-in-the-middle or replay attack can be securely blocked.

SSO will authenticate the customer as an Admin Teammate, with all the permissions to manage any aspect of the customer's account. From there, they can take all the usual steps of setting up API keys, creating additional teammates or subusers, and configuring their sender identity.

This SSO flow is limited to authentication on the base Admin Teammate. It cannot be used for SSO on a subsequently created teammate or subuser.