diff --git a/docs/app-integration-development/20-OAuth-2-Extended-OAuth.md b/docs/app-integration-development/20-OAuth-2-Extended-OAuth.md new file mode 100644 index 0000000..7113002 --- /dev/null +++ b/docs/app-integration-development/20-OAuth-2-Extended-OAuth.md @@ -0,0 +1,67 @@ +--- +tags: [app-integration-development] +--- + +# Extended OAuth + + +> ### Early Access +> +> The features described on this page are in an Early Access state and are subject to change. Your PagerDuty Account may +> require a feature flag before this functionality is available to you. Please reach out to us if you have any questions or +> need support. + +## Register an App +Extended OAuth Clients allow your application to act on a PagerDuty Account as a PagerDuty App. The access your application has to the PagerDuty Account is controlled by the scopes it is granted. Before you start building, you first need to register a PagerDuty App with an Extended OAuth Client. This is done via the Developer Mode UI in your PagerDuty Account. + +The `client_id`, `client_secret` and all selected scopes will be used to obtain an access token. + +## Obtaining an Access Token + +A scoped account token is obtained by making a client credentials request to the token endpoint. + +|Parameter|Description| +|-|-| +|`grant_type`|The OAuth 2.0 grant type. Value must be set to `client_credentials`| +|`client_id`|An identifier issued when the client was added to a PagerDuty App| +|`client_secret`|A secret issued when the client was added to a PagerDuty App| +|`scope`|A space separated list of scopes available to the client. Must contain the `as_account-` scope that specifies the PagerDuty Account the token is being requested for using a `{REGION}.{SUBDOMAIN}` format.| + + +```bash +curl -i --request POST \ + https://identity.pagerduty.com/global/oauth/token \ + --header "Content-Type: application/x-www-form-urlencoded" \ + --data-urlencode "grant_type=client_credentials" \ + --data-urlencode "client_id={CLIENT_ID}" \ + --data-urlencode "client_secret={CLIENT_SECRET}" \ + --data-urlencode "scope=as_account-{REGION}.{SUBDOMAIN} incidents.read services.read" +``` + +The access token will be included in a JSON response along with the scopes that were actually issued to the token. + +```json +{ + "access_token": "pdus+_0XBPWQQ_dfd3c718-4a46-400d-a8ec-45bab1fd417e", + "scope": "as_account-us.pdt-sample incidents.read services.read", + "token_type": "bearer", + "expires_in": 86400 +} +``` + +The token is valid for the number of seconds specified `expires_in` in the response. + +## Using an Access Token + +The access token can be used to access the [REST API](https://developer.pagerduty.com/api-reference/) as a PagerDuty App. + +When making an API request, include the version of the API in the `Accept` header. Access tokens must also be sent in the request as part of the `Authorization` header along with the `Bearer` token type, using this format: + +```http +Authorization: Bearer pdus+_0XBPWQQ_dfd3c718-4a46-400d-a8ec-45bab1fd417e +Accept: application/vnd.pagerduty+json;version=2 +``` + +A `403 - Forbidden` response will be returned if the token does not contain the scope required to access a particular API endpoint +or the API endpoint does not yet support API Scopes. When the token expires a `401 - Unauthorized` response will be returned +and a new token must be obtained. diff --git a/docs/webhooks/07-Webhooks-Beta.md b/docs/webhooks/07-Webhooks-Beta.md index 2e2a90f..d8d957f 100644 --- a/docs/webhooks/07-Webhooks-Beta.md +++ b/docs/webhooks/07-Webhooks-Beta.md @@ -2,10 +2,54 @@ tags: [webhooks] --- -# Webhooks v3 Beta - -import Alert from 'react-bootstrap/Alert' +# Webhooks Early Access -### V3 Webhooks are in Early Access -The v3 Webhook features described on this page are still under development. The features are subject to change at any time. This page is for informational purposes only. \ No newline at end of file +> **Early Access Webhooks v3 Features** +> +> The items described on this page are still under development and are subject to change at any time. This page is for informational purposes only. + +## Event Types + +### incident.action_invocation.created +`data.type` is [`incident_action_invocation`](#incident_action_invocation) + +A Rundeck Action has been newly invoked on an existing Incident. The resource representing this Invocation has a state of "created", indicating it exists, but no progress has been made on it as yet. + +### incident.action_invocation.updated +`data.type` is [`incident_action_invocation`](#incident_action_invocation) + +A Rundeck Action Invocation, running on an Incident, has had its lifecycle state updated. The Invocation is still considered active, and further lifecycle updates are expected. + +### incident.action_invocation.terminated +`data.type` is [`incident_action_invocation`](#incident_action_invocation) + +A Rundeck Action Invocation, running on an Incident, has had its lifecycle state updated to a terminal state. This means it has completed, either successfully or in error, and no further updates will be made. + +## Event Data Types + +### incident_action_invocation + +```json +{ + "id": "01CELD6T9C2JS745I7CAK0LRRF", + "self": "https://api.pagerduty.com/automation/invocations/01CELD6T9C2JS745I7CAK0LRRF", + "html_url": "https://acme.pagerduty.com/rundeck-actions/actions/01CDYN0IRV4VG991K5FR73YNTW/invocations/01CELD6T9C2JS745I7CAK0LRRF/report", + "incident": { + "html_url": "https://acme.pagerduty.com/incidents/PBAZLIU", + "id": "PBAZLIU", + "self": "https://api.pagerduty.com/incidents/PBAZLIU", + "summary": "An Incident", + "type": "incident_reference" + }, + "action": { + "html_url": "https://acme.pagerduty.com/rundeck-actions/actions/01CDYN0IRV4VG991K5FR73YNTW", + "id": "01CDYN0IRV4VG991K5FR73YNTW", + "self": "https://api.pagerduty.com/automation/actions/01CDYN0IRV4VG991K5FR73YNTW", + "summary": "A Helpful Action", + "type": "action_reference" + }, + "state": "created", + "type": "incident_action_invocation" +} +``` diff --git a/toc.json b/toc.json index a28bbf4..6fdceda 100644 --- a/toc.json +++ b/toc.json @@ -264,6 +264,12 @@ "title": "Verifying Signatures", "uri": "docs/webhooks/04-Signatures.md" }, + { + "type": "item", + "title": "Early Access", + "slug": "webhooks/early-access", + "uri": "docs/webhooks/07-Webhooks-Beta.md" + }, { "type": "item", "title": "Public Certificates",