{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid API Keys API", "summary": "The Twilio SendGrid API Keys API allows you manage your API keys and their settings. Your application, mail client, or website can all use API keys to authenticate access to SendGrid services.", "description": "The Twilio SendGrid API Keys API allows you manage your API keys and their settings. Your application, mail client, or website can all use API keys to authenticate access to SendGrid services.\n\nTo create your initial SendGrid API Key, you should use the [SendGrid application user interface](https://app.sendgrid.com/settings/api_keys). Once you have created a first key with scopes to manage additional API keys, you can use this API for all other key management.", "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": "api_keys" } }, "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/api_keys": { "post": { "operationId": "CreateApiKey", "summary": "Create API keys", "tags": [ "API Keys" ], "description": "**This endpoint allows you to create a new API Key for the user.**\n\nTo create your initial SendGrid API Key, you should [use the SendGrid App](https://app.sendgrid.com/settings/api_keys). Once you have created a first key with scopes to manage additional API keys, you can use this API for all other key management.\nA JSON request body containing a `name` property is required when making requests to this endpoint. If the number of maximum keys, 100, is reached, a `403` status will be returned.\nThough the `name` field is required, it does not need to be unique. A unique API key ID will be generated for each key you create and returned in the response body.\nIt is not necessary to pass a `scopes` field to the API when creating a key, but you should be aware that omitting the `scopes` field from your request will create a key with \"Full Access\" permissions by default.\nSee the [API Key Permissions List](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authorization) for all available scopes. An API key's scopes can be updated after creation using the \"Update API keys\" endpoint.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name you will use to describe this API Key." }, "scopes": { "type": "array", "description": "The individual permissions that you are giving to this API Key.", "items": { "type": "string" } } }, "required": [ "name" ], "example": { "name": "My API Key", "scopes": [ "mail.send", "alerts.create", "alerts.read" ] } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string" }, "api_key_id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "examples": { "response": { "value": { "api_key": "SG.xxxxxxxx.yyyyyyyy", "api_key_id": "xxxxxxxx", "name": "My API Key", "scopes": [ "mail.send", "alerts.create", "alerts.read" ] } } } } } }, "400": { "$ref": "#/components/responses/ApiKeysError400" }, "401": { "$ref": "#/components/responses/GlobalError401" }, "403": { "$ref": "#/components/responses/ApiKeysError403" }, "404": { "$ref": "#/components/responses/ApiKeysError404" }, "500": { "$ref": "#/components/responses/GlobalError500" } } }, "get": { "operationId": "ListApiKey", "summary": "Retrieve all API Keys belonging to the authenticated user", "tags": [ "API Keys" ], "description": "**This endpoint allows you to retrieve all API Keys that belong to the authenticated user.**\n\nA successful response from this API will include all available API keys' names and IDs.\n\nFor security reasons, there is not a way to retrieve the key itself after it's created. If you lose your API key, you must create a new one. Only the \"Create API keys\" endpoint will return a key to you and only at the time of creation.\n\nAn `api_key_id` can be used to update or delete the key, as well as retrieve the key's details, such as its scopes.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyResponse" } } } }, "examples": { "response": { "value": { "result": [ { "name": "API Key Name", "api_key_id": "some-apikey-id" }, { "name": "API Key Name 2", "api_key_id": "another-apikey-id" } ] } } } } } }, "401": { "$ref": "#/components/responses/GlobalError401" }, "403": { "$ref": "#/components/responses/GlobalError403" }, "404": { "$ref": "#/components/responses/GlobalError404" }, "500": { "$ref": "#/components/responses/GlobalError500" } } } }, "/v3/api_keys/{api_key_id}": { "parameters": [ { "name": "api_key_id", "in": "path", "description": "", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "GetApiKey", "summary": "Retrieve an existing API Key", "tags": [ "API Keys" ], "description": "**This endpoint allows you to retrieve a single API key using an `api_key_id`.**\n\nThe endpoint will return a key's name, ID, and scopes. If the API Key ID does not, exist a `404` status will be returned.\n\nSee the [API Key Permissions List](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authorization) for all available scopes. An API key's scopes can be updated after creation using the \"Update API keys\" endpoint.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyScopesResponse" } } } }, "examples": { "response": { "value": { "result": [ { "name": "API Key Name", "api_key_id": "some-apikey-id" }, { "name": "API Key Name 2", "api_key_id": "another-apikey-id" } ] } } } } } }, "400": { "$ref": "#/components/responses/ApiKeysError400" }, "401": { "$ref": "#/components/responses/GlobalError401" }, "403": { "$ref": "#/components/responses/ApiKeysError403" }, "404": { "$ref": "#/components/responses/ApiKeysError404" }, "500": { "$ref": "#/components/responses/GlobalError500" } } }, "patch": { "operationId": "UpdateApiKeyName", "summary": "Update API key name", "tags": [ "API Keys" ], "description": "**This endpoint allows you to update the name of an existing API Key.**\n\nYou must pass this endpoint a JSON request body with a `name` property, which will be used to rename the key associated with the `api_key_id` passed in the URL.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new name of the API Key." } }, "required": [ "name" ], "example": { "name": "A New Hope" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" }, "examples": { "response": { "value": { "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", "name": "A New Hope" } } } } } }, "400": { "$ref": "#/components/responses/ApiKeysError400" }, "401": { "$ref": "#/components/responses/GlobalError401" }, "403": { "$ref": "#/components/responses/GlobalError403" }, "404": { "$ref": "#/components/responses/GlobalError404" }, "500": { "$ref": "#/components/responses/GlobalError500" } } }, "put": { "operationId": "UpdateApiKey", "summary": "Update API key name and scopes", "tags": [ "API Keys" ], "description": "**This endpoint allows you to update the name and scopes of a given API key.**\n\nYou must pass this endpoint a JSON request body with a `name` field and a `scopes` array containing at least one scope. The `name` and `scopes` fields will be used to update the key associated with the `api_key_id` in the request URL.\n\nIf you need to update a key's scopes only, pass the `name` field with the key's existing name; the `name` will not be modified. If you need to update a key's name only, use the \"Update API key name\" endpoint.\n\nSee the [API Key Permissions List](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authorization) for all available scopes.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "name" ], "example": { "name": "Profiles key", "scopes": [ "user.profile.read", "user.profile.update" ] } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyResponse" }, "examples": { "response": { "value": { "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", "name": "Profiles Key", "scopes": [ "user.profile.read", "user.profile.update" ] } } } } } }, "400": { "$ref": "#/components/responses/ApiKeysError400" }, "401": { "$ref": "#/components/responses/GlobalError401" }, "403": { "$ref": "#/components/responses/GlobalError403" }, "404": { "$ref": "#/components/responses/GlobalError404" }, "500": { "$ref": "#/components/responses/GlobalError500" } } }, "delete": { "operationId": "DeleteApiKey", "summary": "Delete API keys", "tags": [ "API Keys" ], "description": "**This endpoint allows you to revoke an existing API Key using an `api_key_id`**\n\nAuthentications using a revoked API Key will fail after after some small propogation delay. If the API Key ID does not exist, a `404` status will be returned.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "" }, "400": { "$ref": "#/components/responses/ApiKeysError400" }, "401": { "$ref": "#/components/responses/GlobalError401" }, "403": { "$ref": "#/components/responses/GlobalError403" }, "404": { "$ref": "#/components/responses/GlobalError404" }, "500": { "$ref": "#/components/responses/GlobalError500" } } } } }, "components": { "schemas": { "ApiKeyResponse": { "title": "API Key Name and ID", "type": "object", "properties": { "api_key_id": { "type": "string", "description": "The ID of your API Key. " }, "name": { "type": "string", "description": "The name of your API Key." } }, "example": { "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", "name": "Mail Send" } }, "ApiKeyScopesResponse": { "title": "API Key Name, ID, and Scopes", "example": { "api_key_id": "qfTQ6KG0QBiwWdJ0-pCLCA", "name": "Mail Send", "scopes": [ "mail.send", "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", "sender_verification_eligible", "sender_verification_legacy", "2fa_required" ] }, "type": "object", "properties": { "scopes": { "type": "array", "description": "The permissions this API Key has access to.", "items": { "type": "string" } }, "api_key_id": { "type": "string", "description": "The ID of your API Key. " }, "name": { "type": "string", "description": "The name of your API Key." } } }, "ErrorResponse": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "An error message." }, "field": { "description": "When applicable, this property value will be the field that generated the error.", "nullable": true, "type": "string" }, "help": { "type": "object", "description": "When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error." } } } }, "id": { "type": "string", "description": "When applicable, this property value will be an error ID." } }, "example": { "errors": [ { "field": "field_name", "message": "error message" } ] } } }, "responses": { "ApiKeysError400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ApiKeysError403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ApiKeysError404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "GlobalError401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "GlobalError403": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "GlobalError404": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "GlobalError500": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } }, "parameters": { "OnBehalfOf": { "name": "on-behalf-of", "in": "header", "description": "The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be \"account-id\" followed by the customer account's ID (e.g., `on-behalf-of: account-id `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). See [**On Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.", "required": false, "schema": { "type": "string" } } }, "examples": {}, "requestBodies": {}, "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": "API Keys", "description": "Twilio SendGrid API Keys API." } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }