Twilio SendGrid Scopes API
The Twilio SendGrid Scopes API allows you to retrieve the scopes or permissions available to a user, see the user's attempts to access your SendGrid account, and, if necessary, deny an access request.
OpenAPI Specification
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Scopes API
summary: The Twilio SendGrid Scopes API allows you to retrieve the scopes or permissions
available to a user, see the user's attempts to access your SendGrid account,
and, if necessary, deny an access request.
description: The Twilio SendGrid Scopes API allows you to retrieve the scopes or
permissions available to a user, see the user's attempts to access your SendGrid
account, and, if necessary, deny an access request.
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: scopes
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/scopes:
get:
operationId: ListScope
summary: Retrieve a list of scopes for which this user has access.
tags:
- Scopes
description: '**This endpoint returns a list of all scopes that this user has
access to.**
API Keys are used to authenticate with [SendGrid''s v3 API](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/authorization).
API Keys may be assigned certain permissions, or scopes, that limit which
API endpoints they are able to access.
This endpoint returns all the scopes assigned to the key you use to authenticate
with it. To retrieve the scopes assigned to another key, you can pass an API
key ID to the "Retrieve an existing API key" endpoint.
For a more detailed explanation of how you can use API Key permissions, please
visit our [API Keys documentation](https://sendgrid.com/docs/ui/account-and-settings/api-keys/).'
parameters:
- $ref: '#/components/parameters/OnBehalfOf'
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
scopes:
type: array
description: The list of scopes for which this user has access.
uniqueItems: true
items:
type: string
required:
- scopes
examples:
response:
value:
scopes:
- mail.send
- alerts.create
- alerts.read
'401':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
description: This 401 response indicates that the user making
the call doesn't have the authorization to view the list of
scopes.
items:
type: object
properties:
field:
description: This empty field is returned instead of the
list of scopes if the user making the call doesn't have
the authorization required.
type: string
nullable: true
message:
type: string
description: Explains why the scopes cannot be returned.
required:
- message
required:
- errors
examples:
response:
value:
errors:
- field: null
message: authorization required
'403':
$ref: '#/components/responses/GetScopes403'
'404':
$ref: '#/components/responses/GetScopes404'
'500':
$ref: '#/components/responses/GetScopes500'
/v3/scopes/requests:
get:
operationId: ListScopeRequest
summary: Retrieve access requests
tags:
- Scopes
description: '**This endpoint allows you to retrieve a paginated list of all
recent access requests.**
You can use the `limit` query parameter to set the page size. If your list
contains more items than the page size permits, you can make multiple requests.
Use the `offset` query parameter to control the position in the list from
which to start retrieving additional items.'
parameters:
- name: limit
in: query
description: '`limit` sets the page size, i.e. maximum number of items from
the list to be returned for a single API request. If omitted, the default
page size is used.'
required: false
schema:
type: integer
default: 50
- $ref: '#/components/parameters/PaginationCommonOffset'
responses:
'200':
description: ''
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: integer
description: Request ID
scope_group_name:
type: string
description: Name of group of scopes associated to page teammate
is requesting access to
username:
type: string
description: Teammate's username
email:
type: string
description: Teammate's email
first_name:
type: string
description: Teammate's first name
last_name:
type: string
description: Teammate's last name
examples:
response:
value:
- id: 1
scope_group_name: Mail Settings
username: teammate1
email: [email protected]
first_name: Teammate
last_name: One
- id: 2
scope_group_name: Stats
username: teammate2
email: [email protected]
first_name: Teammate
last_name: Two
/v3/scopes/requests/{request_id}:
parameters:
- name: request_id
in: path
description: The ID of the request that you want to deny.
required: true
schema:
type: string
delete:
operationId: DenyScopeRequest
summary: Deny access request
tags:
- Scopes
description: '**This endpoint allows you to deny an attempt to access your account.**
**Note:** Only teammate admins may delete a teammate''s access request.'
responses:
'204':
description: ''
'401':
description: ''
'404':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
field:
type: string
examples:
response:
value:
errors:
- message: Cannot find request
field: request_id
/v3/scopes/requests/{request_id}/approve:
parameters:
- name: request_id
in: path
description: The ID of the request that you want to approve.
required: true
schema:
type: string
patch:
operationId: ApproveScopeRequest
summary: Approve access request
tags:
- Scopes
description: "**This endpoint allows you to approve an access attempt.**\n\n\
**Note:** Only teammate admins may approve another teammate\u2019s access\
\ request."
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
scope_group_name:
type: string
description: name of feature teammate will be given access to
examples:
response:
value:
scope_group_name: Stats
'401':
description: ''
content:
application/json:
schema:
type: object
'404':
description: ''
content:
application/json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
message:
type: string
field:
type: string
components:
schemas:
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:
GetScopes403:
description: Scopes forbidden response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: access forbidden
field: 'null'
GetScopes404:
description: Scopes not found response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: not found
field: 'null'
GetScopes500:
description: Scopes internal server error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Unauthorized request:
value:
errors:
- message: internal server error
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 <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: <subuser-username>`). 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
PaginationCommonOffset:
name: offset
in: query
required: false
description: The number of items in the list to skip over before starting to
retrieve the items for the requested page. The default `offset` of `0` represents
the beginning of the list, i.e. the start of the first page. To request the
second page of the list, set the `offset` to the page size as determined by
`limit`. Use multiples of the page size as your `offset` to request further
consecutive pages. E.g. assume your page size is set to `10`. An `offset`
of `10` requests the second page, an `offset` of `20` requests the third page
and so on, provided there are sufficiently many items in your list.
schema:
type: integer
minimum: 0
default: 0
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: Scopes
description: Twilio SendGrid Scopes API
externalDocs:
description: Twilio SendGrid's official developer documentation.
url: https://www.twilio.com/docs/sendgrid